Metashape MCP Server — AI-Powered Photogrammetry Automation

A comprehensive Model Context Protocol (MCP) server that brings AI-powered automation to Agisoft Metashape Professional. The Metashape 2.0 compatibility host exposes 112 tools and 14 resources covering photogrammetry workflows from photo alignment to 3D model export.

Use AI to process drone surveys, build 3D models, generate DEMs, create orthomosaics, and export production-ready deliverables — all through conversation.

What This Does

This MCP server runs embedded inside Metashape's Python environment and exposes the entire photogrammetry processing pipeline as AI-callable tools. Instead of manually clicking through menus, you describe what you want and the AI executes the full workflow:

• Drone aerial survey processing — import photos, align cameras, build dense point clouds, generate DEMs and orthomosaics

• Close-range 3D reconstruction — object scanning, artifact digitization, heritage documentation

• Terrain and surface modeling — ground classification, mesh generation, texture mapping

• GCP and marker workflows — survey-grade accuracy with ground control points and coded markers

• Batch export — OBJ, PLY, FBX, TIFF, LAS, and all Metashape-supported formats

• Network processing — submit and monitor jobs on Metashape network processing clusters

Related MCP server: Metashape MCP Server

Features

• 112 tools across 16 modules covering every stage of the photogrammetry pipeline

• 14 resources for real-time project state inspection

• Embedded HTTP host runs on Metashape's Python 3.9+; client proxy uses Python 3.10+

• Streamable HTTP transport (default http://127.0.0.1:8765, port is user-configurable via startup script or METASHAPE_MCP_PORT env)

• Stdio proxy for Claude Code with no timeout limits on long operations

• Progress reporting for dense cloud, mesh, and texture generation

• Full coordinate reference system (CRS/EPSG) support

• Non-blocking UI — the Metashape GUI stays fully interactive while the AI processes in the background

• Headless mode — run without GUI on remote servers, VMs, or CI pipelines for automated processing

Tool Categories

Resources (Real-Time Project Inspection)

Prerequisites

• Agisoft Metashape Professional 2.0+

• Python 3.10+ for the MCP client proxy (the embedded Metashape host uses only the standard library)

Some processing options use Metashape API features added after 2.0 and are unavailable in older versions.

Installation

1. Clone this repository

git clone https://github.com/jenkinsm13/metashape-mcp.git

2. Start the MCP server inside Metashape

The embedded server uses a small standard-library MCP HTTP host, so it does not install packages into Metashape's Python. Install the proxy dependencies in the Python environment used by your MCP clients, as described below.

A ready-to-use startup script is included at scripts/start_mcp_server.py.

The script now displays a small dialog on launch where you can view or change the TCP port used by the MCP server. Your choice is saved in ~/.metashape_mcp_port so subsequent sessions default to the same value. Changing the port will restart the embedded server automatically (if one was already running).

Option A: Auto-start with Metashape (recommended)

1. Edit scripts/start_mcp_server.py and set METASHAPE_MCP_SRC to the path where you cloned this repo's src/ folder

2. Copy the script to Metashape's auto-run scripts folder:

   • Windows: C:\Users\<user>\AppData\Local\Agisoft\Metashape Pro\scripts\

   • macOS: ~/Library/Application Support/Agisoft/Metashape Pro/scripts/

   • Linux: ~/.local/share/Agisoft/Metashape Pro/scripts/

3. Restart Metashape — the MCP server starts automatically

Option B: Run manually via Tools > Run Script

1. Open Metashape

2. Go to Tools > Run Script

3. Select scripts/start_mcp_server.py from this repository

4. The server starts in the background

Option C: From Metashape's Python Console

Open the console (View > Console) and run:

import sys
sys.path.insert(0, r"C:\path\to\metashape-mcp\src")

from metashape_mcp.server import start_background
start_background()
# Server running on http://127.0.0.1:8765/mcp

Important: After starting the server, open the Console panel (View > Console) to monitor MCP operations. You'll see progress updates, tool calls, and status messages as the AI works. The Metashape UI is not blocked — you can continue using menus, viewports, and tools while the AI processes in the background. This lets you visually inspect results in real time as the AI builds your photogrammetry products.

Option D: Headless mode (no GUI — remote servers, VMs, CI pipelines)

For automated processing on machines without a display, run Metashape in headless/offscreen mode with scripts/start_mcp_headless.py:

# Windows:
"C:\Program Files\Agisoft\Metashape Pro\metashape.exe" -platform offscreen -r start_mcp_headless.py

# Linux:
metashape -platform offscreen -r start_mcp_headless.py

# macOS:
/Applications/MetashapePro.app/Contents/MacOS/MetashapePro -platform offscreen -r start_mcp_headless.py

The server runs in the foreground (blocks until Ctrl+C). All processing, export, import, and scripting tools work normally. Viewport/screenshot tools are unavailable in headless mode since there's no display.

Use cases for headless mode: Remote processing servers, cloud VMs, Docker containers, CI/CD pipelines, automated batch processing, and any environment where you want the AI to drive Metashape without a graphical desktop.

3. Connect your AI client

Understanding the architecture (read this first)

┌──────────────────┐      stdio (no timeout)      ┌──────────────────┐      HTTP       ┌──────────────────┐
│   Claude Code    │ ◄──────────────────────────► │   proxy.py       │ ◄─────────────► │   Metashape      │
│   (AI client)    │                               │   (FastMCP)      │                  │   (port 8765)    │
└──────────────────┘                               └──────────────────┘                  └──────────────────┘

Two things are running:

1. The HTTP server inside Metashape — started in Step 2 above, listens on http://127.0.0.1:8765/mcp

2. The stdio proxy (proxy.py) — a tiny FastMCP process that Claude Code spawns. It forwards tool calls from stdio to the HTTP server with a 24-hour timeout instead of the default ~60 seconds.

Why not connect Claude Code directly to http://127.0.0.1:8765/mcp?

You can, and it works for quick operations. But photogrammetry operations take minutes to hours (dense point clouds, mesh building, texturing large datasets). Claude Code's HTTP transport has a hard ~60-second read timeout. When a tool call takes longer than that, the connection drops and the operation appears to fail — even though Metashape is still processing. The stdio proxy has no timeout, so operations can run for as long as they need.

Claude Code (recommended setup — stdio proxy)

Multiple MCP instances?

1. Choose a different port for each Metashape session using the startup script dialog or METASHAPE_MCP_PORT env var.

2. Configure the same port on the agent side:

   • For the stdio proxy, set METASHAPE_MCP_PORT in the environment where you launch proxy.py (it uses the variable to build its URL).

   • For direct HTTP connections, include the port in the url field of your .mcp.json or Claude Desktop config (e.g. "url": "http://127.0.0.1:8766/mcp"). This ensures the client talks to the right server instead of the default 8765 instance.

This is the setup you almost certainly want. It handles both quick operations and hour-long processing without timeout failures.

Step 1: The workspace already has a Python 3.12 environment with the proxy dependencies installed. If you use a different clone, install FastMCP in that client-side Python (not Metashape's Python 3.9):

# Find your Python's full path
python -c "import sys; print(sys.executable)"

# Install FastMCP in that Python (NOT Metashape's Python)
pip install "fastmcp>=2.0.0"

Multiple Python installations? If you have multiple Pythons (Miniconda, Windows Store, standalone installs), Claude Code may pick a different one than your terminal uses. The "command" in Step 2 must point to the Python that has fastmcp installed. Use the full path from the command above instead of just "python" to avoid ambiguity — e.g., "command": "C:/Users/you/AppData/Local/.../python.exe".

Step 2: This checkout already registers metashape-local in Claude Code's user scope. For another machine, configure .mcp.json like this:

{
  "mcpServers": {
    "metashape": {
      "command": "python",
      "args": ["-m", "metashape_mcp.proxy"],
      "env": {
        "PYTHONPATH": "C:/path/to/metashape-mcp/src"
      }
    }
  }
}

Replace C:/path/to/metashape-mcp/src with the actual path to where you cloned this repo's src/ directory. For example: "PYTHONPATH": "C:/Users/you/Documents/metashape-mcp/src"

Replace python with the full path to the Python executable that has fastmcp installed if you have multiple Python installations. See the note in Step 1.

Step 3: Start Metashape with the MCP server, then run /mcp in Claude Code. Confirm metashape-local is connected. Ask Claude: Inspect the open Metashape project using the read-only status tools and summarize its current state.

Claude Code (direct HTTP — NOT recommended)

Warning: This works for quick operations but will timeout and fail on any operation taking longer than ~60 seconds. This includes dense point cloud generation, mesh building, texturing, and many other core photogrammetry operations. Use the stdio proxy above instead.

{
  "mcpServers": {
    "metashape": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "metashape": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Claude Desktop connects directly to the local HTTP endpoint. Start Metashape first, then fully restart Claude Desktop after saving the config.

VS Code and Antigravity

This checkout includes .vscode/mcp.json for VS Code MCP clients. Open the workspace, start Metashape, then reload MCP servers from the Chat view. Select Agent mode and ask it to inspect the open project. The server entry launches the local stdio proxy, which is preferable to a direct HTTP connection for long calls.

Antigravity IDE uses %USERPROFILE%\\.gemini\\antigravity\\mcp_config.json (in this setup it resolves to %USERPROFILE%\\.gemini\\config\\mcp_config.json). The Metashape stdio proxy entry has been added without replacing the existing server. Restart Antigravity after starting Metashape, then check its MCP tools list and use the same natural-language requests as in Claude.

Gemini CLI

Gemini CLI supports local stdio MCP servers. Add this entry to %USERPROFILE%\\.gemini\\settings.json under mcpServers if you use Gemini CLI rather than Antigravity IDE:

{
  "mcpServers": {
    "metashape": {
      "command": "C:/path/to/metashape-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "metashape_mcp.proxy"],
      "env": {
        "PYTHONPATH": "C:/path/to/metashape-mcp/src",
        "METASHAPE_MCP_PORT": "8765"
      },
      "timeout": 86400000
    }
  }
}

Replace the two paths with this checkout's paths. Start Metashape first; use /mcp in Gemini CLI to confirm it connected.

ChatGPT

ChatGPT web cannot connect directly to 127.0.0.1. Use OpenAI's Secure MCP Tunnel: create a tunnel in Platform tunnel settings, run tunnel-client on this computer pointing at http://127.0.0.1:8765/mcp, then add a custom MCP server in ChatGPT with Connection: Tunnel and select that tunnel. ChatGPT custom MCP availability depends on your plan/workspace permissions. Tunnel requests have a 120-second deadline, so use a local stdio client such as Claude Code, Antigravity, or VS Code for lengthy reconstructions.

How to chat with Metashape

Start with a read-only request, for example: Use Metashape MCP to inspect the current project and report the active chunk, camera alignment count, and available products. Do not modify anything. For processing, state the project, inputs, desired output, and quality. Have the model inspect the project first and request confirmation before irreversible or lengthy changes. Metashape must remain running with the server active while you chat.

Usage Examples

Drone Aerial Survey

Process my drone survey:
- Project path: C:/projects/site_survey.psx
- Photos folder: C:/photos/drone_flight_001/
- Coordinate system: EPSG:32633 (UTM Zone 33N)
- Quality: high
- Deliverables: DEM + orthomosaic as GeoTIFF

3D Object Reconstruction

Reconstruct a 3D model of this artifact:
1. Create a new project at C:/projects/artifact.psx
2. Add photos from C:/photos/artifact_scan/
3. Align cameras and build dense point cloud
4. Generate high-quality mesh with texture
5. Export as OBJ with texture atlas

GCP Workflow for Survey-Grade Accuracy

Set up GCPs for my survey project:
1. Open project C:/projects/cadastral.psx
2. Detect coded markers in all photos
3. Import GCP coordinates from C:/gcp/control_points.csv
4. Optimize camera alignment with GCP constraints
5. Build orthomosaic at 2cm GSD

Custom Python Scripts (YOLO masking, batch workflows, etc.)

The execute_python tool gives the AI full access to Metashape's embedded Python runtime. It can import any package installed in Metashape's environment and run arbitrary code:

Run a YOLO model to generate masks for all photos:
- Use ultralytics to detect objects in each camera image
- Generate binary masks and apply them in Metashape
- Then rebuild the dense point cloud without the masked regions

Write a custom batch script that:
1. Opens every .psx file in C:/projects/batch/
2. Rebuilds the mesh at medium quality
3. Exports each as FBX to C:/exports/
4. Saves and closes each project

The AI has access to Metashape, app, doc, and chunk variables pre-loaded, plus any library you've pip-installed into Metashape's Python (numpy, opencv-python, ultralytics, pillow, etc.).

Inspect Project State

What's the current state of my Metashape project?
How many cameras are aligned? What's the reprojection error?
What processing steps are still needed?

Architecture

src/metashape_mcp/
├── server.py           # FastMCP entry point, Streamable HTTP transport
├── proxy.py            # Stdio-to-HTTP proxy for Claude Code
├── tools/              # 15 modules organized by photogrammetry stage
│   ├── project.py      # Project management and GPU configuration
│   ├── photos.py       # Photo import and quality analysis
│   ├── camera.py       # Camera/sensor configuration and masking
│   ├── alignment.py    # SfM: matching, alignment, optimization
│   ├── dense.py        # MVS: depth maps, dense cloud, classification
│   ├── mesh.py         # 3D mesh generation and editing
│   ├── texture.py      # UV mapping and texture generation
│   ├── survey.py       # DEM, orthomosaic, tiled model, contours
│   ├── export.py       # Multi-format export (OBJ, PLY, FBX, LAS, TIFF)
│   ├── import_data.py  # Import models, point clouds, reference data
│   ├── markers.py      # Coded markers, GCPs, scalebars
│   ├── coordinate.py   # CRS/EPSG, bounding region, transforms
│   ├── network.py      # Network processing server interaction
│   ├── viewport.py     # 3D viewport control and screenshots
│   └── scripting.py    # Arbitrary Python code execution (YOLO, batch, custom)
├── resources/          # 14 read-only project state resources
├── prompts/            # Prompt templates (not exposed by the compatibility host)
└── utils/
    ├── bridge.py       # Safe Metashape API access with error handling
    ├── enums.py        # String-to-Metashape enum parameter mapping
    └── progress.py     # Async progress callback adapter

Key design patterns:

• Bridge layer — All Metashape API calls go through utils/bridge.py for safe access with clear error messages when no project is open or a required processing step hasn't been completed

• Enum mapping — Human-readable string parameters (e.g., "high", "aggressive") are automatically mapped to Metashape's internal enum values

• Progress reporting — Long operations (dense cloud, mesh, texture) report progress percentage via MCP's progress callback system

• GPU/CPU management — CPU is automatically enabled only during alignment operations; disabled for all GPU-accelerated processing (dense cloud, meshing, texturing) where it would slow things down

Troubleshooting

Frequently Asked Questions

What is metashape-mcp?

metashape-mcp is an open-source MCP (Model Context Protocol) server that connects Agisoft Metashape Professional to AI assistants like Claude. It lets you automate photogrammetry workflows using natural language instead of manual GUI interaction or Python scripting.

Can I use this to automate drone mapping?

Yes. metashape-mcp supports the complete drone aerial survey pipeline: importing geotagged photos, aligning cameras with Structure from Motion (SfM), building dense point clouds with Multi-View Stereo (MVS), generating Digital Elevation Models (DEMs), creating orthomosaics, and exporting to GeoTIFF and other standard formats. It also supports GCP (Ground Control Point) workflows for survey-grade accuracy.

What AI assistants work with this?

Any MCP-compatible AI assistant can connect. This includes Claude Desktop, Claude Code, and any other application that supports the Model Context Protocol. The server uses Streamable HTTP transport and also provides a stdio proxy for clients that need it.

Does this replace Metashape's GUI?

No. The MCP server runs alongside Metashape's GUI. Metashape must be open and running for the server to function. The AI assistant sends commands to Metashape through the MCP server, and you can still use the GUI simultaneously to inspect results, adjust viewports, or make manual corrections.

What photogrammetry formats can I export?

metashape-mcp supports all export formats available in Metashape Professional, including: OBJ, PLY, FBX, COLLADA, STL, DXF, U3D, PDF for 3D models; LAS/LAZ for point clouds; GeoTIFF for DEMs and orthomosaics; Cesium 3D Tiles for web; KMZ for Google Earth; and Agisoft's native formats.

Can I process ground control points (GCPs)?

Yes. The markers tools support detecting coded markers, manually placing GCPs, importing GCP coordinates from CSV files, creating scalebars for scale constraints, and optimizing camera alignment with GCP reference data. This enables survey-grade positional accuracy in your photogrammetry outputs.

How does this handle long-running operations?

Photogrammetry operations like dense point cloud generation and mesh building can take minutes to hours depending on dataset size. The included stdio proxy (proxy.py) bridges the AI client to the HTTP server without timeout limits, ensuring operations complete fully. Progress percentage is reported back to the AI in real time.

Can I run this without a GUI (headless mode)?

Yes. metashape-mcp supports headless operation for remote servers, cloud VMs, Docker containers, and CI/CD pipelines. Run Metashape with -platform offscreen and the headless startup script. All photogrammetry processing, export, import, scripting, and network tools work normally in headless mode — only the viewport/screenshot tools require a display. This lets you set up fully automated AI-driven photogrammetry pipelines on machines without a graphical desktop.

Can the AI run custom Python scripts in Metashape?

Yes. The execute_python tool gives the AI full access to Metashape's Python 3.12 runtime. It can write and run arbitrary code — import third-party libraries like YOLO/ultralytics, OpenCV, NumPy, or Pillow, script custom batch workflows across multiple projects, generate masks from ML models, do image processing, or anything else Python can do. The AI has pre-loaded access to the Metashape module, the active document, and the active chunk.

What version of Metashape do I need?

Agisoft Metashape Professional 2.0 or newer can run the embedded server. Some individual tools require API features introduced in later versions. The embedded MCP host supports Metashape's Python 3.9 runtime; the external stdio proxy requires Python 3.10 or newer.

Keywords

Agisoft Metashape, MCP server, Model Context Protocol, photogrammetry automation, AI photogrammetry, drone mapping, aerial survey, 3D reconstruction, point cloud processing, mesh generation, texture mapping, DEM generation, orthomosaic creation, GCP workflow, ground control points, Structure from Motion, SfM, Multi-View Stereo, MVS, Claude AI, Claude Desktop, Claude Code, LLM photogrammetry, LiDAR classification, geospatial, remote sensing, surveying, digital twin, heritage documentation, Cesium 3D Tiles, GeoTIFF export, headless photogrammetry, batch processing, YOLO masking, Python scripting, automated pipeline, CI/CD photogrammetry

License

MIT