Gdal Mcp

gdal-mcp

向 AI Agent 提供 GDAL/Rasterio 操作的 MCP 服务，并带有反思中间件：对于方法选择很重要的操作（CRS 选择、重采样方法、查询范围），执行前必须提供结构化说明。

安装

通过 uvx（推荐）

uvx --from gdal-mcp gdal --transport stdio

通过 Docker

docker build -t gdal-mcp .
docker run -i gdal-mcp gdal --transport stdio

本地开发

git clone https://github.com/Wayfinder-Foundry/gdal-mcp.git
cd gdal-mcp
uv sync
uv run gdal --transport stdio

配置 MCP 客户端

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/， Windows：%APPDATA%\Claude\，Linux：~/.config/Claude/）：

{
  "mcpServers": {
    "gdal-mcp": {
      "command": "uvx",
      "args": ["--from", "gdal-mcp", "gdal", "--transport", "stdio"],
      "env": {
        "GDAL_MCP_WORKSPACES": "/path/to/your/geospatial/data"
      }
    }
  }
}

重启 Claude Desktop。此时应显示 MCP 服务指示器，并且可以使用 raster_* 和 vector_* 工具。

工作区范围限制

GDAL_MCP_WORKSPACES 是一个以冒号分隔的目录列表，指定服务允许访问的目录。 如果未设置，则允许访问所有路径，并记录一条警告。

可选的工具范围标志：RASTER=true、VECTOR=true。完整列表请参阅 docs/ENVIRONMENT_VARIABLES.md。

工具

• 栅格： raster_info、raster_convert、raster_reproject、raster_stats、raster_query
• 矢量： vector_info、vector_convert、vector_reproject、vector_clip、vector_buffer、vector_simplify、vector_query
• **资源：**目录（workspace://...）、元数据（metadata://...）、参考资料（reference://...）、查询结果（query://result/{id}）
• 提示词： justify_crs_selection、justify_resampling_method、justify_query_extent（以及 src/prompts/ 中的更多提示词）

参数、返回结构和示例请参阅 TOOLS.md。

反思中间件

对于方法选择很重要的工具，调用 Agent 必须先提供结构化说明，否则工具不会执行。流程如下：

1. Agent 调用例如 raster_reproject(dst_crs="EPSG:3857", resampling="cubic", ...)。
2. 中间件会在 .preflight/justifications/{domain}/ 中检查是否存在匹配的哈希值。
3. 如果未找到，调用会抛出 ToolError，并提示使用相关提示词（例如 justify_crs_selection）。
4. Agent 调用该提示词，填写 Justification 模式（意图、考虑过的替代方案、选择、权衡、置信度），然后通过 __reflection 负载重新调用工具。
5. 说明会按领域缓存，因此后续调用 raster_reproject 和 vector_reproject 时，针对 EPSG:3857 的 CRS 说明都能满足要求。

模式和缓存布局请参阅 docs/REFLECTION.md，了解此功能的缘由请参阅 docs/PHILOSOPHY.md。

文档

• TOOLS.md — 工具参考
• docs/ENVIRONMENT_VARIABLES.md — 运行时配置
• docs/REFLECTION.md — 反思中间件内部机制
• docs/PHILOSOPHY.md — 设计理念与方向
• docs/ROADMAP.md — 发布历史与方向
• CHANGELOG.md — 版本变更记录
• CONTRIBUTING.md — 贡献指南

故障排除

Access denied: path outside allowed workspaces — 将相关目录添加到 GDAL_MCP_WORKSPACES 中（参阅“工作区范围限制”）。

MCP 客户端看不到服务 — 先确认 uvx --from gdal-mcp gdal --help 可以独立运行，然后在编辑配置文件后重启客户端。

License

MIT — see LICENSE.

Built on FastMCP, Rasterio, pyogrio, and Shapely.