Metashape MCP

Metashape MCP服务器——基于人工智能的摄影测量自动化

   

全面 模型上下文协议 （MCP）服务器，带来 AI驱动的自动化到Agisoft Metashape Professional.106个工具、10个资源和6个提示，涵盖了从照片对齐到3D模型导出的整个摄影测量流程，通过Claude、Claude Code或任何兼容MCP的AI助手使用自然语言。

使用人工智能处理无人机调查、构建3D模型、生成演示、创建正射影像，并通过对话导出生产就绪的交付成果。

这有什么作用

此MCP服务器嵌入在Metashape的Python环境中运行，并公开 整个摄影测量处理流程 作为人工智能可调用工具。您无需手动点击菜单，只需描述所需内容，AI即可执行完整的工作流程：

• 无人机航测处理 --导入照片、对齐相机、构建密集点云、生成DEM和正交拼接
• 近距离三维重建 --物体扫描、人工制品数字化、遗产文献
• 地形和表面建模 --地面分类、网格生成、纹理映射
• GCP和标记工作流程 --地面控制点和编码标记的测量等级精度
• 批量导出 --OBJ、PLY、FBX、TIFF、LAS和所有Metashape支持的格式
• 网络处理 --提交和监视Metashape网络处理集群上的作业

特性

• 106工具 横跨15个模块，涵盖摄影测量流程的每个阶段
• 10资源 用于实时项目状态检查
• 6个提示 用于指导工作流程（航空测量、近距离、诊断）
• 在Metashape的嵌入式Python 3.12中本机运行
• 流式HTTP传输（默认 http://127.0.0.1:8765，端口可通过启动脚本或METASHAPE_MCP_port环境由用户配置）
• 克劳德代码的Stdio代理，对长时间操作没有超时限制
• 密集云、网格和纹理生成的进度报告
• 全坐标参考系（CRS/EPSG）支持
• 非阻塞UI --当AI在后台处理时，Metashape GUI保持完全交互
• 无头模式 --在远程服务器、虚拟机或CI管道上无需GUI即可运行，以实现自动化处理

工具类别

资源（实时项目检查）

引导式工作流提示

先决条件

• Agisoft Metashape Professional 2.3+ （使用Python 3.12脚本）
• MCP Python SDK 和 FastMCP --启动脚本首次运行时自动安装

安装

1.克隆此存储库

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

2.在Metashape中启动MCP服务器

依赖项会自动安装。 启动脚本检测到丢失的包(mcp, fastmcp)并在第一次运行时将它们安装到Metashape的Python中。不需要手动pip命令。

现成的启动脚本包含在 scripts/start_mcp_server.py.

脚本现在在启动时显示一个小对话框，您可以在其中查看或 更改MCP服务器使用的TCP端口。您的选择已保存在 ~/.metashape_mcp_port 因此，后续会话默认为相同的会话 价值。更改端口将自动重新启动嵌入式服务器 （如果其中一个已经在运行）。

选项A：使用Metashape自动启动（推荐）

1. 编辑 scripts/start_mcp_server.py 并设置 METASHAPE_MCP_SRC 指向您克隆此仓库的路径 src/ 文件夹
2. 将脚本复制到Metashape的自动运行脚本文件夹：

- 窗户： C:\Users\\AppData\Local\Agisoft\Metashape Pro\scripts\ - macOS： ~/Library/Application Support/Agisoft/Metashape Pro/scripts/ - Linux： ~/.local/share/Agisoft/Metashape Pro/scripts/

1. 重新启动Metashape--MCP服务器自动启动

选项B：通过“工具”>“运行脚本”手动运行

1. 打开图元形状
2. 首选 工具>运行脚本
3. 选择 scripts/start_mcp_server.py 来自此存储库
4. 服务器在后台启动

选项C：来自Metashape的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

重要提示： 启动服务器后，打开Console面板(查看>控制台)以监控MCP操作。当AI工作时，您将看到进度更新、工具调用和状态消息。这 Metashape UI未被阻止 --当AI在后台处理时，您可以继续使用菜单、视口和工具。这使您可以在AI构建摄影测量产品时实时直观地检查结果。

选项D：无头模式（无GUI——远程服务器、VM、CI管道）

对于没有显示器的机器上的自动处理，请在无头/屏幕外模式下运行Metashape 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

服务器在前台运行（直到Ctrl+C）。所有处理、导出、导入和脚本工具都正常工作。由于没有显示器，因此在无头模式下无法使用视口/屏幕截图工具。

无头模式的用例： 远程处理服务器、云虚拟机、Docker容器、CI/CD管道、自动批处理以及任何您希望AI在没有图形桌面的情况下驱动Metashape的环境。

3.连接您的AI客户端

了解架构（先阅读此内容）

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

有两件事正在运行：

1. Metashape内部的HTTP服务器 --从上述步骤2中开始，继续收听 http://127.0.0.1:8765/mcp
2. stdio代理 (proxy.py)--Claude Code生成的一个微小的FastMCP进程。它将工具调用从stdio转发到HTTP服务器，并使用 24小时超时 而不是默认的~60秒。

为什么不直接将Claude Code连接到 http://127.0.0.1:8765/mcp? 你可以，而且它适用于快速操作。但是 摄影测量操作需要几分钟到几小时 （密集点云、网格构建、纹理化大型数据集）。Claude Code的HTTP传输有大约60秒的读取超时。当工具调用所需时间超过此时间时，连接会断开，操作似乎会失败——即使Metashape仍在处理中。stdio代理具有 无超时，因此操作可以根据需要运行。

______________________________________________________________________

Claude Code（推荐设置--stdio代理）

多个MCP实例？ 1. 使用以下命令为每个Metashape会话选择不同的端口 启动脚本对话框或 METASHAPE_MCP_PORT 有人是。 1. 在上配置相同的端口 代理人方面: - 对于stdio代理，设置 METASHAPE_MCP_PORT 在环境中 在哪里发射 proxy.py （它使用变量来构建其URL）。 - 对于直接HTTP连接，请在 url 领域 你的 .mcp.json 或Claude桌面配置（例如。 "url": "http://127.0.0.1:8766/mcp"). 这确保了客户端与正确的服务器进行通信，而不是 默认8765实例。

这是你几乎肯定想要的设置。 它既能处理快速操作，也能处理长达一小时的处理，而不会出现超时故障。

第一步： 找到将使用的Python Claude代码，并在那里安装FastMCP：

# 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"

多个Python安装？ 如果你有多个Python（Miniconda、Windows Store、独立安装），Claude Code可能会选择一个与你的终端不同的Python。这 "command" 在步骤2中，必须指向具有以下特性的Python fastmcp 安装。使用 完整路径 从上面的命令而不是仅仅 "python" 为了避免歧义，例如。， "command": "C:/Users/you/AppData/Local/.../python.exe".

第二步： 添加到您的 .mcp.json （要么 ~/.claude/.mcp.json 全球，或 .mcp.json 在项目根目录中）：

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

替换 C:/path/to/metashape-mcp/src 带有克隆此仓库的实际路径 src/ 目录。 例如： "PYTHONPATH": "C:/Users/you/Documents/metashape-mcp/src" 替换 python 具有以下Python可执行文件的完整路径 fastmcp 如果您有多个Python安装，则安装。请参阅步骤1中的注释。

步骤3： 验证它是否正常工作--重新启动Claude Code（或运行 /mcp 重新连接），然后让Claude列出Metashape工具。您应该看到106个工具出现。

______________________________________________________________________

克劳德代码（直接HTTP——不推荐）

警告： 这适用于快速操作，但 将超时并在任何超过约60秒的操作中失败这包括密集点云生成、网格构建、纹理和许多其他核心摄影测量操作。请改用上面的stdio代理。

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

______________________________________________________________________

克劳德桌面版

添加 claude_desktop_config.json:

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

Claude Desktop管理自己的HTTP连接，并以与Claude Code不同的方式处理长时间运行的操作。直接HTTP在这里工作得很好。

用法示例

无人机航空测量

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

三维物体重建

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测量等级精度工作流程

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

自定义Python脚本（YOLO掩码、批处理工作流等）

这 execute_python 该工具使AI可以完全访问Metashape的Python 3.12运行时。它可以导入安装在Metashape环境中的任何软件包并运行任意代码：

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

AI可以访问 Metashape, app, doc，以及 chunk 预加载的变量，以及您在Metashape的Python中安装的任何库（numpy、opencv-Python、ultralytics、pillow等）。

检查项目状态

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?

建筑

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/          # 10 read-only project state resources
├── prompts/            # Guided workflow and troubleshooting templates
└── utils/
    ├── bridge.py       # Safe Metashape API access with error handling
    ├── enums.py        # String-to-Metashape enum parameter mapping
    └── progress.py     # Async progress callback adapter

关键设计模式：

• 架桥车 -所有Metashape API调用都通过 utils/bridge.py 用于在没有打开项目或未完成所需的处理步骤时进行安全访问，并显示清晰的错误消息
• 枚举映射 --人类可读的字符串参数（例如。， "high", "aggressive")会自动映射到Metashape的内部枚举值
• 进度报告 --长操作（密集云、网格、纹理）通过MCP的进度回调系统报告进度百分比
• GPU/CPU管理 --CPU仅在对齐操作期间自动启用；禁用所有GPU加速处理（密集云、网格、纹理），因为这会减慢速度

故障排除

常见问题

什么是metashape mcp？

metashape-mcp是一个开源的mcp（模型上下文协议）服务器，它将Agisoft metashape Professional与Claude等人工智能助手连接起来。它允许您使用自然语言自动化摄影测量工作流程，而不是手动GUI交互或Python脚本。

我可以用它来自动绘制无人机地图吗？

对。metashape mcp支持完整的无人机航空测量流程：导入地理标记照片，将相机与运动结构（SfM）对齐，使用多视图立体（MVS）构建密集点云，生成数字高程模型（DEM），创建正射镶嵌，以及导出为GeoTIFF和其他标准格式。它还支持GCP（地面控制点）工作流程，以实现测量级精度。

什么样的人工智能助手可以使用它？

任何兼容MCP的AI助手都可以连接。这包括Claude Desktop、Claude Code和支持模型上下文协议的任何其他应用程序。服务器使用Streamable HTTP传输，并为需要它的客户端提供stdio代理。

这会取代Metashape的GUI吗？

不是。MCP服务器与Metashape的GUI一起运行。Metashape必须打开并运行，服务器才能运行。AI助手通过MCP服务器向Metashape发送命令，您仍然可以同时使用GUI检查结果、调整视口或进行手动更正。

我可以导出哪些摄影测量格式？

metashape mcp支持metashape Professional中提供的所有导出格式，包括：OBJ、PLY、FBX、COLLADA、STL、DXF、U3D、3D模型的PDF；LAS/LAZ表示点云；GeoTIFF用于DEM和正射影像；用于网络的铯3D瓷砖；KMZ代表谷歌地球；以及Agisoft的原生格式。

我可以处理地面控制点（GCP）吗？

对。标记工具支持检测编码标记、手动放置GCP、从CSV文件导入GCP坐标、为比例约束创建比例尺，以及优化相机与GCP参考数据的对齐。这使得您的摄影测量输出具有测量级的位置精度。

这如何处理长时间运行的操作？

密集点云生成和网格构建等摄影测量操作可能需要几分钟到几小时，具体取决于数据集的大小。附带的stdio代理(proxy.py)将AI客户端连接到HTTP服务器，没有超时限制，确保操作完全完成。进度百分比实时报告给AI。

我可以在没有GUI（无头模式）的情况下运行它吗？

对。metashape-mcp支持远程服务器、云VM、Docker容器和CI/CD管道的无头操作。使用运行Metashape -platform offscreen 以及无头启动脚本。所有摄影测量处理、导出、导入、脚本和网络工具都在无头模式下正常工作——只有视口/屏幕截图工具需要显示。这使您可以在没有图形桌面的机器上设置完全自动化的人工智能驱动的摄影测量管道。

AI可以在Metashape中运行自定义Python脚本吗？

对。这 execute_python 该工具使AI可以完全访问Metashape的Python 3.12运行时。它可以编写和运行任意代码——导入YOLO/ultlytics、OpenCV、NumPy或Pillow等第三方库，跨多个项目编写自定义批处理工作流，从ML模型生成掩码，进行图像处理，或Python可以做的任何其他事情。AI预加载了对Metashape模块、活动文档和活动块的访问权限。

我需要什么版本的Metashape？

需要Agisoft Metashape Professional 2.3或更高版本。服务器使用Metashape的嵌入式Python 3.12环境和2.3版中引入的API功能。

关键词

Agisoft Metashape、MCP服务器、模型上下文协议、摄影测量自动化、AI摄影测量、无人机测绘、航测、3D重建、点云处理、网格生成、纹理测绘、DEM生成、正射镶嵌创建、GCP工作流、地面控制点、运动结构、SfM、多视图立体、MVS、Claude AI、Claude Desktop、Claude Code、LLM摄影测量、LiDAR分类、地理空间、遥感、测量、数字孪生、遗产文档、Cesium 3D Tiles、GeoTIFF导出、无头摄影测量、批处理、YOLO掩模、Python脚本、自动化管道、CI/CD摄影测量

许可证

麻省理工学院