Skip to main content
Glama
geospatial-mcp
by fly2cd

geospatial-mcp

面向 AI Agent 的地理空间 MCP(Model Context Protocol)服务。以 stdio 传输独立运行,不依赖任何特定 Agent、模型或外部配置。

能力概览

  • 只读元数据检查:矢量(GeoJSON / GeoPackage / Shapefile)与栅格(GeoTIFF)的图层、CRS、字段、几何与边界信息。

  • 有界矢量分析:平面缓冲区、裁剪、空间连接(需启用工作区)。

  • 矢量制图:渲染带图例、CRS 与坐标边界的 PNG 地图,不发起任何网络请求。

  • 任务与成果管理:每次分析生成隔离任务;成果(GPKG / PNG)通过 MCP resource 以真实字节交付,带 SHA256 校验。

  • 受控数据访问:仅通过管理员登记的 dataset_id 引用数据,不接受调用方提供的服务器路径或 URL。

Related MCP server: GIS MCP Server

工具一览

工具

说明

需要工作区

geo_vector_info

矢量元数据:图层、CRS、字段、几何类型、要素数、边界

否

geo_raster_info

栅格元数据:尺寸、波段、CRS、边界、像元大小、NoData

否

geo_list_datasets

列出已登记数据集 ID 与类型,不暴露服务器路径

是

geo_vector_buffer

平面缓冲区,保留属性,输出 GPKG

是

geo_vector_clip

用多边形掩膜裁剪,保留源属性

是

geo_spatial_join

一对多平面空间连接(intersects / within / contains)

是

geo_render_vector_map

渲染 PNG 矢量地图,可选数值字段色带

是

geo_get_task_info

读取任务状态、参数、警告与输出元数据

是

geo_get_artifact_info

读取成果元数据(ID、URI、大小、SHA256)

是

另提供 resource artifact://{artifact_id},用于读取已完成成果的 GPKG / PNG 二进制内容。完整输入输出契约见 docs/工具参考.md。

安装

推荐在项目目录使用独立环境:

uv sync --locked --python 3.12 --cache-dir .cache/uv

或安装为 Python 包:

python -m pip install . --cache-dir .cache/pip

pip install . 使用声明的直接依赖;需要完整可复现依赖时使用 uv sync --locked。

快速开始

# 生成小型合成演示数据(不下载外部数据)
.\.venv\Scripts\python.exe examples\create_demo_data.py --output examples\data

# 指向数据目录并以 stdio 启动
$env:GEO_DATA_ROOT = (Resolve-Path examples\data).Path
.\.venv\Scripts\geospatial-mcp.exe --transport stdio

stdio 服务通常由 MCP 客户端在连接时自动拉起;手动运行后等待输入属正常行为。也可执行 python -m geospatial_mcp --transport stdio。--help 与 --version 不需要配置数据目录。

配置

数据目录

默认读取 $GEO_DATA_ROOT/datasets.json,由管理员登记可对外暴露的数据集:

{
  "version": 1,
  "datasets": {
    "roads_demo": {"path": "roads.geojson", "kind": "vector"},
    "dem_demo": {"path": "dem.tif", "kind": "raster"}
  }
}

路径必须相对于数据根目录,禁止 ..、绝对路径、URL 与 Windows ADS。目录在启动时加载,变更后需重启;每次调用仍会重新校验实际路径、文件存在性与大小。不要在数据目录中放置模型配置或凭证。

环境变量

变量

默认值

说明

GEO_DATA_ROOT

必填

已存在的绝对数据目录

GEO_DATA_CATALOG

<GEO_DATA_ROOT>/datasets.json

数据目录 JSON 的绝对路径

GEO_MAX_INPUT_BYTES

268435456

单个输入最大字节数(256 MiB)

GEO_MAX_VECTOR_FEATURES

1000000

元数据扫描要素上限,超限报错

GEO_WORKSPACE_ROOT

空

设置后启用分析与成果工作区(绝对路径,须与数据目录互不包含)

GEO_MAX_ANALYSIS_FEATURES

100000

单个分析输入要素上限

GEO_MAX_OUTPUT_FEATURES

100000

单个成果输出要素上限

GEO_MAX_ARTIFACT_BYTES

16777216

单个成果最大字节数(16 MiB)

GEO_LOG_LEVEL

INFO

日志级别,写 stderr 不写协议 stdout

不设置 GEO_WORKSPACE_ROOT 时仅提供两个元数据工具;设置后启用全部 9 个工具与成果 resource。

工作区与成果

启用工作区后,每个分析工具创建一个隔离任务,输出 GPKG 或 PNG 成果。流程为:

  1. 调用分析工具(如 geo_vector_buffer),返回 task_id 与成果元数据(artifact_id、uri、size_bytes、sha256)。

  2. 用 geo_get_task_info / geo_get_artifact_info 查询任务与成果状态。

  3. 通过 resources/read 读取 artifact://{artifact_id} 获取真实文件字节,而非服务器文件路径。

矢量成果可在后续分析中作为 artifact_id 输入复用,形成链式分析。

客户端接入

采用 mcpServers 配置格式的客户端示例(按你的实际安装路径替换):

{
  "mcpServers": {
    "geospatial": {
      "command": "<项目目录>/.venv/Scripts/geospatial-mcp.exe",
      "args": ["--transport", "stdio"],
      "env": {
        "GEO_DATA_ROOT": "<数据目录绝对路径>"
      }
    }
  }
}

工具发现与调用不依赖客户端当前工作目录。Hermes 等 Agent 的接入方式见 docs/Hermes接入指南.md。

验证

# 不调用任何 LLM 的普通 stdio 客户端验证
.\.venv\Scripts\python.exe examples\stdio_client.py --data-root $env:GEO_DATA_ROOT

# 单元测试(生成合成数据,不访问模型)
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

也可使用 MCP Inspector 做交互式调试(仅调试用途,非运行依赖):

npx --yes @modelcontextprotocol/inspector --cli -e "GEO_DATA_ROOT=$env:GEO_DATA_ROOT" .\.venv\Scripts\geospatial-mcp.exe --method tools/list

安全边界与限制

  • 仅适用于可信管理员维护、客户端不可修改的数据目录;不提供多用户认证授权。

  • 目录授权与符号链接检查不构成完整沙箱;不防御管理员并发替换文件的 TOCTOU,也不保证恶意原生格式解析的进程隔离。

  • 大小限制是文件大小限制,不是解压或解析内存上限。

  • 输入目录应设置为只读;应用不修改输入,但不能替代操作系统权限。

  • Shapefile 需完整存放于受控目录;不支持远程 URL、GDAL VRT、压缩归档与不可信 pickle。

  • 仅提供 stdio 传输;HTTP、上传、进程级硬超时与资源隔离尚未实现,见 docs/架构与路线图.md。

文档

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers