geo-explorer-mcp

geo-explorer-mcp

已列入 mcprush：https://mcprush.com/arnienemeth/geo-explorer-mcp

一个 MCP 服务，以结构化数据的形式提供国家概况、行政边界和区域统计数据，让 AI 助手能够构建交互式地理内容，而不是照本宣科。

该服务有意返回数据，而非文字。它提供人口、边界多边形和坐标；由模型决定如何呈现这些数据——可以是可点击的地图、对比表，也可以是斯洛伐克语、德语或匈牙利语课程。该服务不具备翻译功能，也无需具备。

工具

工具	参数	返回内容
get_country_profile	country	首府及其坐标、人口、面积、地区、货币、语言（英文和本地名称）、邻国、国旗、Wikipedia 链接
get_map_data	country、level = ADM0 | ADM1 | ADM2	地区名称和可由浏览器获取的 GeoJSON URL，以及来源、许可证、数据年份和数据质量警告
get_region_details	country	各地区的人口、面积、首府（包括其人口和坐标）、本地名称、细分类型、Wikidata 和 Wikipedia 链接

country 可使用几乎任何语言的名称，例如 Slovakia、Slovensko、Magyarország、Magyarorszag（不含变音符号）、Deutschland、Ungarn。

这两个边界和统计工具专为联合使用而设计：get_region_details 会为每个地区返回一个 match_key，并提供 join_hint，告知模型如何规范化 get_map_data 返回的名称，以便进行匹配。

快速开始

git clone https://github.com/arnienemeth/geo-explorer-mcp
cd geo-explorer-mcp
uv sync

将 .env.example 复制为 .env 并填写内容：

RESTCOUNTRIES_API_KEY=rc_live_...          # free: https://restcountries.com/sign-up
GEO_EXPLORER_CONTACT=https://github.com/you/your-repo

GEO_EXPLORER_CONTACT 会写入发送给 Wikidata 的 User-Agent。Wikimedia 要求提供联系 URL 或电子邮件，否则会以 403 响应。

发布到 PyPI 后，也可以不克隆项目直接安装：

uvx geo-explorer-mcp

在 MCP Inspector 中试用：

uv run fastmcp dev inspector server.py

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Windows 上的路径为 %APPDATA%\Claude\claude_desktop_config.json），并相应调整路径：

{
  "mcpServers": {
    "geo-explorer": {
      "command": "C:\\path\\to\\geo-explorer-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\geo-explorer-mcp\\server.py"]
    }
  }
}

指定项目自身的 .venv 解释器，就能让 Claude 运行与你测试过的完全相同的内容，无需维护第二个环境以保持同步。之后请彻底重启 Claude Desktop——配置只会在启动时读取。

然后可以向它提出类似这样的请求：

用德语为我展示一张斯洛伐克各地区的交互式地图，并按人口着色。

演示页面

demo/index.html 使用与服务相同的两个数据源，在浏览器中将它们关联起来，并呈现四个国家中的任意一个：按人口、面积或密度着色，标注首府，提供可排序表格，以及指向各地区 Wikipedia 和 Wikidata 的链接。一个页面，通过参数指定国家——因为该服务具有通用性。

页面必须通过 http 提供服务，不能作为文件打开——file:// 页面具有 null 源，浏览器会阻止其跨源请求：

cd demo
python -m http.server 8000

	地区数	与统计数据关联数
斯洛伐克	8 个州	8
德国	16 个联邦州	16
英国	4 个构成国	4
美国	56 个州和领地	55

美国唯一未匹配的是维尔京群岛，Wikidata 中没有它的 ISO 3166-2 条目。没有匹配项的地区会显示为灰色，而不会被移除。

目录结构

server.py                      entry point kept at the root (a shim)
src/geo_explorer_mcp/server.py the implementation
demo/index.html                the browser demo
server.json                    MCP registry metadata

根目录中的 server.py 会重新导出服务对象，因此 Claude Desktop 配置、fastmcp dev inspector server.py 和探测脚本仍可正常运行，同时底层软件包也可保持可发布状态。

测试

uv run python probe2.py        # all three tools, plus the boundary/statistics join
uv run python probe_names.py   # country-name resolution across languages and spellings

probe2.py 会运行全部四个演示国家，并断言两个曾经出错的项目：geojson_url 是已解析的 Git LFS 媒体 URL；至少 90% 的边界地区能与对应统计数据关联。引入本地名称匹配之前，德国的匹配率只有 50%。

实战笔记

记录那些会耗费大量调试时间的问题，避免它们也耗费你的时间。

REST Countries v3.1 已经停用。 网上几乎所有教程仍在使用它。v5 位于不同的主机，需要 bearer token，并且重命名了每个字段 （area → area.kilometers、cca3 → codes.alpha_3，而 capitals 现在是 对象数组，不再是字符串）。

geoBoundaries GeoJSON 存储在 Git LFS 中，只有 media.githubusercontent.com 会向浏览器提供它：

• raw.githubusercontent.com/... 返回的是131 字节的 LFS 指针文件，而不是几何数据。
• API 发布的 github.com/.../raw/... URL 会通过 302 重定向，且其 access-control-allow-origin 为空。浏览器会在重定向的每一跳都执行 CORS 检查，因此页面获取它时会失败并报错 TypeError: Failed to fetch，尽管最终响应发送了 access-control-allow-origin: *。

这两种错误都会导致地图空白且没有错误提示。get_map_data 会解析重定向，并返回实际可用的 URL。

用 curl 验证并不能验证浏览器行为。 curl -L 会顺利跟随该重定向，并报告最终响应中的宽松标头。 它完全不处理 CORS。请使用带有 Origin 标头的跨源 fetch，或在浏览器中测试。

Wikidata 的面积属性混用了单位。 P2046 的值可能以平方公里、公顷或平方米录入，原始数字不会标明使用的是哪种单位。直接读取时，Békéscsaba 的面积竟显示为 193,930,000 km²——实际是 193.9 km²，记录单位为 m²。请使用标准化值 （p:P2046/psn:P2046），Wikidata 会将其转换为 SI 基本单位。

ISO 3166-2 混合了不同的行政级别。 匈牙利返回 43 个下级行政区：19 个州、布达佩斯，以及 23 个享有州级权利的城市。这些城市位于各州之内，因此不能将它们的面积和人口相加，而且边界形状也远少于条目数。get_region_details 会返回 subdivision_types，并通过 data_quality_notes 发出警告。

国家名称匹配会折叠大小写，但不会折叠变音符号。 Magyarország 可以匹配； Magyarorszag 则不行。翻译名称（Ungarn、Hongrie）会被有意排除在名称聚合之外。服务端通过三步回退来处理这两种情况：名称聚合、翻译端点，然后是本地构建的变音符号折叠索引。

适用于小国的 Wikidata 查询，在大国可能会超时。 通过 ?i wdt:P17 ?country 解析下级行政区，会让 Wikidata 扫描该国的所有数据：对斯洛伐克来说没问题，对美国则会返回 HTTP 504。改为按 ISO 3166-2 前缀筛选——FILTER(STRSTARTS(?iso, "US-"))——可在 0.9 秒内返回相同的 56 行，因为这些代码的格式定义为<alpha-2>-<subdivision>，所以前缀本身就是国家筛选条件。

同一个地区在不同数据源中名称各异。 geoBoundaries 使用 Bayern、Sachsen、Thüringen；Wikidata 的英文标签则是 Bavaria、 Saxony、Thuringia。仅按英文标签匹配，只能关联上德国 16 个州中的 8 个。使用所有名称变体（包括本地名称）构建键后，才能关联全部 16 个州——这也是 get_region_details 返回 match_keys（复数形式）的原因。

跨越日期变更线的形状，其边界框会产生误导。 阿拉斯加的阿留申群岛延伸至 180° 以外，因此边界框显示为 -179.15 .. 179.78——跨度达 359 度。对它调用 fitBounds 会缩小到整个地球，令大陆部分缩成一小块，而且不会报错。俄罗斯、斐济和新西兰也有同样的问题。该演示会拒绝任何宽度超过 180° 的边界框，并回退到固定视图。

任何作者定义的 display 规则都会覆盖 hidden 属性。 它通过浏览器默认样式表（优先级最低的样式来源）生效，因此设置 hidden 后，使用 display:grid 样式的元素仍会显示。现象是：加载遮罩层一直不消失，覆盖着已完美加载的地图。请用 [hidden]{display:none !important} 进行保护。 部分上游地区名称已损坏。 geoBoundaries 中斯洛伐克的 ADM2 名称被截断且转写错误（Prešov → Predov，Dolný Kubín → Dolne Kub）。几何数据正常。get_map_data 会检测到这一问题，并返回 data_quality_note，以免模型将损坏的名称当作事实呈现。

单行折叠的 SPARQL 查询中不要包含 # 注释。 在 SPARQL 中，# 会注释掉该行的剩余内容；折叠后， 整条查询都会被注释。症状：HTTP 400。

数据源

来源	用途	许可协议
REST Countries v5	国家信息	免费层级，需 API 密钥
geoBoundaries	行政边界	CC BY 4.0 / ODbL，因国家而异 — 工具会针对每次请求返回实际许可协议
Wikidata	地区统计数据、首府、链接	CC0 1.0

边界数据的许可协议因国家而异，因为 geoBoundaries 汇总了各国的数据源。斯洛伐克的边界数据源于 OpenStreetMap，因此采用 ODbL，该许可协议包含 CC BY 没有的相同方式共享义务。get_map_data 会返回刚刚提供的数据所适用的许可协议；请使用该许可协议，不要使用硬编码的字符串。

路线图

• 发布到 PyPI，使 MCP 服务可通过 uvx geo-explorer-mcp 安装
• 通过关联 Wikidata 修复损坏的 ADM2 名称
• 添加 compare_countries，用于并排比较统计数据
• 将边界元数据缓存到磁盘，而非内存中

许可协议

MIT — 参见 LICENSE。此 MCP 服务返回的数据各自适用不同的许可协议；参见上表。