Skip to content
Conduit

mcp server

gfm-mcp

MCP server exposing Geospatial Foundation Model inference to LLM agents — building extraction, landcover/water segmentation, change detection, GFM embeddings. CPU-capable, 16 tools.

yuyi1008688/gfm-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gfm-mcp": {
      "command": "uvx",
      "args": [
        "gfm-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 22, 2026

gfm-mcp

把地理空间基础模型（GFM）的推理能力封装为 MCP 工具，让任何 LLM 智能体"动嘴"调用遥感深度学习。

EN: Expose Geospatial Foundation Model (GFM) inference — building extraction, water segmentation, object detection, change detection, zero-shot scene classification, and GFM embeddings — as Model Context Protocol tools for any LLM agent. Runs on CPU.

License: GPL v3 Tools Python

📖 实战演示: docs/DEMO_zh.md —— 真实客户端对话记录：一句话驱动 GFM 建筑物提取 + Moran's I + 交互制图 🔧 踩坑档案: docs/PITFALLS.md —— 23 条真实排障记录（Windows / CPU-only / 国内网络）

本项目是一次开源空白的填补尝试：MCP（协议）× GIS Copilot（对话式 GIS）× GFMs（地理空间基础模型） 三方向的交汇处，截至 2026-08 没有成熟的完整开源实现（GitHub 相关检索最大 star 仅为 5 的雏形项目，"gfm mcp"关键词甚至被 GitHub Flavored Markdown 占据）。gfm-mcp 用 11 个任务级工具补上这块拼图。

你: "帮我对这张影像做建筑物提取，再把结果做空间自相关分析"
        │
LLM 智能体（Cherry Studio / Claude Desktop / ...）
        │ MCP 协议
        ├─< gis-mcp（经典空间分析：98 工具，缓冲区/Moran's I/NDVI/数据下载）
        └─< gfm-mcp（本项目：GFM 推理 11 工具，建筑物/水体/检测/变化/嵌入）

工具清单（11 + 1 路线图）

族工具功能上游能力本地硬件
目录list_gfm_models21 个 GFM 目录（名称/模态/任务/年份/HF 仓库）geoai-py秒级
目录get_model_info模糊查询单模型详情geoai-py秒级
推理extract_buildings建筑物轮廓提取 → GeoJSON（CPU 实测 30s/2500px 影像，664 栋）geoai-py✅ CPU
推理segment_water水体提取（NAIP/Sentinel-2 波段可配）geoai-py✅ CPU
推理detect_objects目标检测（solar_panel / ship / car）geoai-py✅ CPU
推理detect_change双时相变化检测（ChangeStar）geoai-py✅ CPU（tile 调小）
推理classify_sceneCLIP 零样本场景判读（无需训练）transformers✅ CPU
嵌入list_embedding_models20 个嵌入模型清单 + 网络要求标注rs-embed秒级
嵌入gfm_embedding任意坐标提取基础模型嵌入：tessera 128维/6s、gse(AlphaEarth) 64维/18s、galileo 192维/20s(GEE)rs-embed✅ 需代理(GEE)
嵌入embedding_similarity两地嵌入余弦相似度（实测 cos=0.9923）rs-embed✅ 需代理
嵌入embedding_cluster区域网格嵌入 + K-Means 地表形态分区（3×3 实测 222s）rs-embed✅ 需代理
异步start_job / check_task长耗时推理转后台任务（规避客户端超时），轮询取结果自研✅
域classify_threshold_levels物理阈值+分位数五级分级（源自月球极区光照分类法）自研✅ CPU
域dem_precision_fuse双 DEM 精度倒数加权融合（源自 LOLA+CE-2 法）自研✅ CPU
域poi_vitalityPOI 活力指数（KDE + Shannon 熵，源自教育资源优化项目）自研✅ CPU
路线图finetune_remote（阶段4）触发 Colab 远程微调TerraTorch云端

⚠️/✅ 需代理 = 嵌入数据托管在 Google 基础设施。2026-08-29 已在代理环境下全量实测通过（128 维向量/6s、相似度、聚类）；无代理环境返回结构化错误 + 换网络建议（门控设计，不崩会话）。

快速开始

# 1) 宿主环境（Python 3.12+，本包的重量级上游）
uv pip install fastmcp geoai-py rs-embed

# 2) 安装本包
uv pip install -e ./gfm-mcp

# 3) MCP 客户端配置（Claude Desktop / Cherry Studio / Cursor 通用）
{
  "mcpServers": {
    "gfm-mcp": {
      "command": "<venv路径>/python.exe",
      "args": ["-m", "gfm_mcp"]
    }
  }
}

# 4) 测试（可选: 下载示例影像供 heavy 组使用，国内走镜像约 6s/12.7MB）
curl -L -o tests/data/naip_train.tif https://hf-mirror.com/datasets/giswqs/geospatial/resolve/main/naip_train.tif

python tests/test_gfm_mcp.py fast     # 快测: 目录/清单/门控（无需数据，~1min）
python tests/test_gfm_mcp.py domain   # 域工具+异步模式（自动合成数据）
python tests/test_gfm_mcp.py heavy    # 影像推理组（需测试影像，含模型首下载）
python tests/test_gfm_stdio.py        # stdio 握手 + 16 工具清点

国内网络注意：本包在 import 时自动设置 HF_ENDPOINT=https://hf-mirror.com 兜底（用户环境变量已设时不覆盖）。

设计决策（踩坑驱动）

  1. 惰性导入：geoai/torch 等重库只在工具被调用时 import——服务器冷启动 2.9s（对照 gis-mcp 全量 extras 冷启动 8s+，它把导入放在了模块顶层）。
  2. 实现/装饰器分离：所有逻辑是普通函数（*_impl），MCP 工具只是薄封装——绕开 FastMCP FunctionTool 不可直接调用的坑，函数级测试无需走 MCP 协议。
  3. 网络门控：嵌入族工具对 Google 数据源不可达返回 {"status":"error","hint":"..."} 而非异常，保证智能体会话不崩。
  4. 上游 bug 绕过：geoai 0.42.0 masks_to_vector(regularize=True) 触发 arctan2 类型错误，工具内部固定 regularize=False 并注释原因。
  5. 异步任务模式：MCP 客户端对单次调用有超时窗口（Cherry Studio 默认约 60s）， 而 CPU 推理需 1-3 分钟——start_job 秒回任务号、后台线程执行、check_task 轮询。 实测：建筑物提取 59.6s 后台完成，客户端零超时。
  6. 任务级粒度：一个工具 = 一个完整地理任务（含模型下载/推理/矢量化/统计），而非一个函数——减少 LLM 的工具选择负担（对照 gis-mcp 的 98 个函数级工具，两台服务器正好互补）。

数据流示例（Claude 客户端实测语句）

"对 C:/geoai_demo/naip_v2.tif 提取建筑物"
  → extract_buildings → {"count": 664, "median_area_m2": 215, "output": ".../naip_v2_buildings.geojson"}

"这张影像最像以下哪类: 机场/农田/居民区/森林?"
  → classify_scene → {"top": "residential area", "confidence": 0.71, ...}

已验证环境

Windows 11 x64 · Python 3.12.14 (uv venv) · CPU-only（AMD Ryzen 7 8745H / 16GB RAM，无独立 GPU）· geoai-py 0.42.0 / torch 2.13.0+cpu / fastmcp 2.13.1 / rs-embed 0.2.1。 建筑物提取实测：2503×1126 NAIP 影像 664 栋 / 52-71s（CPU）。

致谢与定位

  • 模型与推理引擎：geoai-py（Qiusheng Wu）、rs-embed（CyberGIS）
  • 协议层：FastMCP、Model Context Protocol
  • 经典空间分析姊妹服务器：gis-mcp
  • 本项目 = 协议封装与系统集成（GPL-3.0-or-later，衍生作品须同协议开源并署名），不含任何新模型；价值在"早 + 闭环 + 文档化"。

路线图

  • 0.1.0 — 11 工具（目录/推理/嵌入三族），CPU 全链路验证
  • 0.2.0 — 域工具族 3 个（竞赛方法论工具化：五级分级/DEM 融合/POI 活力），共 14 工具
  • 0.2.1 — 异步任务模式（start_job/check_task），共 16 工具，彻底解决客户端超时
  • 0.2.2 — 嵌入族代理环境实测通过（128 维/相似度/聚类），坑24 修复（Embedding.data）
  • 0.2.3 — GEE 全线贯通：OAuth→非商业注册→项目绑定→galileo on-the-fly 嵌入（192维/20s）+ GSE/AlphaEarth（64维/18s）；坑25/26
  • GEE 认证后扩展 on-the-fly 模型嵌入（galileo/prithvi 等非预计算路径）
  • 0.3.0 — finetune_remote：TerraTorch 微调任务下发到 Colab，产物回传注册
↑↓ navigate openesc close