Model Context Protocol · Stdio JSON-RPC 2.0

Connect AI agents to your local drone footage without uploading video.

drone-path mcp starts a local Model Context Protocol server over stdin and stdout. Agents query your spatial archive, inspect targeted keyframes and telemetry, export NLE markers, and render flight-path videos while raw 4K footage stays on your disk.

npx drone-path mcp --allow-root /path/to/footage

Safety boundaries

Strict filesystem confinement by design

Every file and directory argument accepted by an MCP tool is validated before any read, FFmpeg invocation, or file write occurs.

Mandatory --allow-root jail

You must pass at least one existing directory via --allow-root <dir...>. Each root is resolved canonically via realpath, and every input path, discovered clip, and planned output path is verified inside those roots after resolving symlinks and .. segments.

Protected state & safe defaults

Archive queries filter results to clips inside the allowed roots. Tools cannot overwrite the archive SQLite database (or its -wal, -shm, and -journal files), export_markers and render_map_video refuse to overwrite existing files unless DRONE_PATH_MCP_ALLOW_OVERWRITE=1 is set, and render_map_video caps calls at 10 recordings.

Client setup

Configure your MCP client

Add Drone Path to any MCP-compatible host (such as Claude Desktop or Cursor) and point --allow-root at the folders containing your DJI recordings. Diagnostics go to stderr with absolute filesystem paths redacted.

{
  "mcpServers": {
    "drone-path": {
      "command": "npx",
      "args": [
        "-y",
        "drone-path",
        "mcp",
        "--allow-root",
        "/path/to/drone-footage"
      ]
    }
  }
}
Server options and environment variables
Option / EnvRequirementPurpose
--allow-root <dir...>RequiredOne or more existing directories confining all tool inputs and outputs
--archive-db <path>OptionalOverride the default per-user SQLite archive database path
DRONE_PATH_MCP_ALLOW_OVERWRITEOptional (1 / true)Allow export_markers and render_map_video to overwrite existing files

Tool catalog

Nine tools exposed over MCP

Agents can index clips, search by geography or shot kinematics, inspect telemetry and frames, and produce NLE markers or map renders.

Tools available in drone-path mcp
ToolPurposeKey arguments
archive_scanIndex MP4 folders into the SQLite archivedirs, recurse?, prune?
archive_list_clipsList matching indexed clipsbbox?, after?/afterMs?, before?/beforeMs?, minDistanceM?, availability?, segmentType?, minSmoothness?
archive_list_flightsList matching clips grouped into inferred flightsSame filter fields as archive_list_clips
archive_find_at_pointFind clips passing near or viewing a coordinatelat, lon, radiusM?, includeGaze?
archive_list_segmentsList kinematic shot segments ordered by smoothnessSame filter fields as archive_list_clips
clip_get_telemetryProbe a clip and return telemetry summary, shot segments, and sampled track recordsvideoPath, includeSamples?, maxSamples? (1–2000)
clip_extract_keyframesExtract JPEG keyframes and telemetry snapshotsvideoPath, at (string or array), maxWidth?, outDir?
export_markersWrite DaVinci Resolve CSV or FCPXML markers from ranges or archive filtersoutputPath, ranges? or filters?
render_map_videoRender flight-path map overlay videos and optional tracks (max 10 inputs per call)inputs, style?, view?, zoom?, trailColor?, hud?, codec?, quality?, trackOut?, frameStart?, frameEnd?

Agent workflows

Example tasks you can ask an AI assistant

Location & gaze discovery

“Scan my trip folder, find every recording whose camera gaze passed over 46.62, 14.31 within 250 m, and summarize the flights.”

Automated shot culling

“List smooth-glide shots with smoothness above 0.85, extract two preview keyframes per shot, and export DaVinci Resolve timeline markers.”

Targeted map rendering

“Render a topographic map overlay with speed and altitude HUD for the selected clip's best segment and save a GPX track beside it.”