Metashape MCP Server
README.md
# Metashape MCP Server — AI-Powered Photogrammetry Automation
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://www.agisoft.com/)
A comprehensive [Model Context Protocol](https://modelcontextprotocol.io/) (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
## 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
| Module | Tools | Capabilities |
|--------|-------|-------------|
| **project** | 12 | Create, open, save projects; manage/merge/align/duplicate chunks; GPU/CPU config; processing status |
| **photos** | 5 | Import photos and video frames, analyze image quality, remove/rename cameras |
| **camera** | 8 | Enable/disable/select cameras, configure sensors, import/clear masks, camera metadata and reference |
| **alignment** | 6 | Structure-from-Motion (SfM): match photos, align cameras, optimize, filter tie points, reset alignment |
| **dense** | 12 | Multi-View Stereo (MVS): depth maps, dense point cloud, ground classification, filtering, smoothing, colorization |
| **mesh** | 8 | 3D mesh generation, decimation, smoothing, hole closing, mesh refinement, cleaning, colorization |
| **texture** | 5 | UV mapping, texture atlas generation, color calibration, texture removal |
| **survey** | 8 | DEM generation, orthomosaic creation, tiled models, contour lines, panoramas, raster export |
| **export** | 10 | Export to OBJ, PLY, FBX, LAS/LAZ, GeoTIFF, Cesium 3D Tiles, cameras, reference, report, and more |
| **import** | 6 | Import models, point clouds, reference data, camera calibrations, shapes, masks |
| **markers** | 9 | Detect coded markers, add/remove GCPs, create/remove scalebars, set reference, import/export markers |
| **coordinate** | 8 | Set CRS (EPSG codes), define bounding region, update coordinate transform, reprojection, localization |
| **network** | 5 | Network processing: connect, batch submit, list, monitor, abort |
| **viewport** | 3 | Capture viewport screenshots, read console output, auto-save project |
| **scripting** | 1 | Execute arbitrary Python code inside Metashape's environment |
### Resources (Real-Time Project Inspection)
| URI | Description |
|-----|-------------|
| `metashape://project/info` | Project path, save status, chunk count |
| `metashape://project/chunks` | All chunks with processing state summary |
| `metashape://chunk/{label}/summary` | Detailed chunk statistics and quality metrics |
| `metashape://chunk/{label}/cameras` | Camera list with alignment status and error metrics |
| `metashape://chunk/{label}/sensors` | Sensor calibration parameters (focal length, distortion) |
| `metashape://chunk/{label}/tie_points` | Tie point count, projections, reprojection error |
| `metashape://chunk/{label}/point_cloud` | Dense point cloud statistics and classification |
| `metashape://chunk/{label}/model` | 3D model geometry — faces, vertices, texture resolution |
| `metashape://chunk/{label}/dem` | Digital Elevation Model extent and resolution |
| `metashape://chunk/{label}/orthomosaic` | Orthomosaic dimensions and ground sampling distance |
## 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
```bash
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`](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:
```python
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`](scripts/start_mcp_headless.py):
```bash
# 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):
```bash
# 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:
```json
{
"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.
```json
{
"mcpServers": {
"metashape": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
```
---
#### Claude Desktop
Add to `claude_desktop_config.json`:
```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:
```json
{
"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](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels): 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
| Problem | Solution |
|---------|----------|
| **Server won't start** | The embedded host uses the Python standard library. Check the Metashape Console for import or API errors, and verify `METASHAPE_MCP_SRC` points to this repository's `src` directory. Install `fastmcp` in the separate Python 3.10+ environment used by your MCP client, not in Metashape. |
| **Connection refused** | Start the server inside Metashape first (Step 2), then configure your AI client. The server must be running before connecting. |
| **"Failed to reconnect" in Claude Code** | **Most common cause:** Claude Code is spawning a different Python than the one with `fastmcp` installed. Check the debug log at `~/.claude/debug/` for `ModuleNotFoundError: No module named 'fastmcp'`. Fix: use the **full path** to the Python executable that has `fastmcp` installed in your `.mcp.json` `"command"` field instead of just `"python"`. Also verify: (1) you're using the stdio proxy config, not direct HTTP; (2) Metashape is running with the server started. Test the HTTP server directly with: `curl -s -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' http://127.0.0.1:8765/mcp` |
| **Timeout / dropped connection on long operations** | You're using direct HTTP instead of the stdio proxy. Switch to the stdio proxy config — direct HTTP has a ~60s timeout that kills long-running photogrammetry operations. See "Claude Code (recommended setup)" above. |
| **Import errors** | Ensure the `PYTHONPATH` in your `.mcp.json` points to `metashape-mcp/src`. If running manually, use `sys.path.insert(0, "/path/to/metashape-mcp/src")`. |
| **"No document open"** | Open or create a Metashape project before running processing tools. Use the `open_project` or `create_project` tool. |
## 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](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues