StatsMapped Public Data

statsmapped-mcp

一个 MCP 服务，将 StatsMapped 的 公共 API 作为工具提供给 AI Agent（Claude Desktop、Cursor 和其他 MCP 客户端）使用。

StatsMapped 跟踪爱尔兰（按郡划分）和英国（按地方政府辖区划分）的公开数据，涵盖住房、 犯罪、健康、经济和社会福利，数据来自官方发布机构（爱尔兰的 CSO、PSRA、Central Bank of Ireland、DHLGH、NTPF、Office of Government Procurement、EU Publications Office； 英国的 ONS/HM Land Registry/Nomis/DfE/DfT），每个数据都附有各自的注意事项。本软件包让 Agent 可以直接通过工具调用查询这些数据，而不必抓取和解析网页。以下每个工具都接受 country 参数（"ireland" 或 "united-kingdom"，默认值为 "ireland"）——两国跟踪的 数据集和地理层级确实不同，因此请针对实际需要的国家调用 query_data/list_areas，不要 假设爱尔兰的默认设置也适用。

这是一个轻量客户端。它调用 StatsMapped 已公开、无需身份验证的 HTTPS API （文档见 statsmapped.com/openapi.json）；以下功能均无需 API 密钥。默认通过 stdio 在你自己的机器上运行（目前推荐的使用方式）——有关此软件包 也支持的托管 streamable-http 模式及其相应的实际权衡，请参阅 为何使用 stdio。

安装

已发布到 PyPI，包名为 statsmapped-mcp（已确认可用：https://pypi.org/project/statsmapped-mcp/）：

pip install statsmapped-mcp

配置

将以下内容添加到 MCP 客户端的配置中（Claude Desktop 使用 claude_desktop_config.json；Cursor 使用等效的 mcp.json）：

{
  "mcpServers": {
    "statsmapped": {
      "command": "statsmapped-mcp"
    }
  }
}

工具

4 个工具（由原来的 9 个合并而来——query_data 和 compare 各自是一个工具，根据传入的参数选择不同模式，而不是几个几乎相同的单一用途工具）。每个工具都接受 country 参数（"ireland" 或 "united-kingdom"，默认值为 "ireland"）——爱尔兰和英国跟踪的数据集和地理层级不同，因此请针对所需国家调用 query_data/list_areas，不要假定爱尔兰的默认值同样适用。

• **query_data(area_id=None, dataset=None, history_months=0, country="ireland")****——三种模式：
  • 不传入 area_id 和 dataset：某个国家中 StatsMapped 跟踪的所有统计数据，包括其键、 标签，以及发布时采用的地理层级。请从这里开始。
  • 传入 area_id，不传入 dataset：某个地区可用的所有数据集（例如，爱尔兰的 "county:kerry"，英国的 "uk:lad:e09000033"），以及每个数据集的最新数值和 同比变化。注意事项仅提供标签和严重程度，不含完整文本——目的是在为某个数据集的完整详情付费前，先决定哪些数据集值得关注。
  • 同时传入 area_id 和 dataset：某个地区中某个数据集的完整详情——文字摘要、完整的注意事项文本，以及（可选，通过 history_months 指定）近期历史数据。
• list_areas(level="county", country="ireland")——指定边界层级下的所有地理区域。 level 默认为爱尔兰的 26 个郡；英国自己的主要层级是 "lad"（地方政府区），而非 "county"——每个国家也都有其他层级（爱尔兰还包括 local_authority/garda_division）。
• compare(stat_key=None, level=None, pair_key=None, stat_key_a=None, stat_key_b=None, country="ireland") ——四种模式，每次只能使用一组参数（混用会引发错误）：
  • 仅传入 stat_key：指定层级下的所有区域，按该统计数据的最新数值从高到低排序。
  • 仅传入 pair_key：某个已注册对比组合的完整详情——各轴的标签/单位/发布方、相关性统计数据（r、rho、留一敏感性范围）以及注意事项。pair_key 来自下方的无参数模式。
  • 同时传入 stat_key_a 和 stat_key_b：StatsMapped 是否已注册这两项统计数据之间经过人工审核的对比？仅限注册表中的对比——绝不会针对任意组合计算新的相关性。comparable 是一个字符串，而不是布尔值："yes"（已注册且经过人工审核的组合；pair_key 会标明其名称）、"no"（两项统计数据没有任何共同的地理层级），或 "unknown"（未注册，但也未排除：应视为“询问人工”，而不是“大概可以”）。"unknown" 是大多数组合的常见结果。请显式比较数值（result["comparable"] == "yes"）；真值判断对三种结果都会返回真。reasons（列表）始终会说明答案。
  • 以上参数均不传入：某个国家中所有已注册的跨数据集对比组合（例如 “房屋中位售价与每 1,000 名居民的新建住宅竣工数”）。这是一个小型的人工整理集合，并非任意组合引擎。
• explain_metric(stat_key, country="ireland")——某项统计数据的定义、方法和常见注意事项，不提供当前数值。当问题涉及某项指标的含义或测量方式，而非某个地区的数值时，请使用此工具。

为什么默认使用 stdio，而不是托管服务

StatsMapped 运行在单个免费层级实例上。托管在该实例上的远程 MCP 端点，会让 Agent 自身的多区域查询模式（循环调用同一个工具，每个区域调用一次）复现此前在该实例上因地理范围扇出过大而导致超时的负载模式。使用 stdio 运行意味着每次调用都会通过你自己的网络连接，访问本软件包的工具直接调用的同一个公共 HTTPS API，不会产生共享瓶颈——每位用户都由自己的机器发起 HTTP 调用，因此 N 位用户的流量会自然分散到 N 个源 IP，而不会集中到一个 IP。

server.py 也支持真正的托管 streamable-http 模式（MCP_TRANSPORT=streamable-http），供愿意接受这种权衡的部署使用——StatsMapped 的公共 API 本身按源 IP 限流（每小时 600 个请求），但托管的 MCP 端点会通过同一个共享出口 IP 代理所有远程用户的调用，因此托管端点的所有远程用户会共用同一个配额，而不是各自拥有独立配额。StatsMapped 托管的端点已上线，地址为 https://mcp.statsmapped.com/mcp（Streamable HTTP）——已确认可正常响应，直接支持 Streamable HTTP 的客户端无需单独安装。裸域名（https://mcp.statsmapped.com，不带路径）也会重定向到同一端点，方便使用。

开发

cd mcp-server
pip install -e .
python tests/test_client.py

测试套件会针对真实的线上 API 运行（默认使用 https://statsmapped.com，也可使用 STATSMAPPED_MCP_BASE_URL 指定）——仅执行只读 GET 请求，不会写入任何数据，也不需要密钥。

许可

本软件包采用 MIT 许可。底层数据遵循各发布方自己的许可——在将任何数据用于通过 Agent 查询以外的用途之前，请查看 statsmapped.com/ireland/sources，了解爱尔兰各发布方及其许可的详情（目前还没有对应的英国页面——在此期间，请查看每个英国工具响应中的 caveats/sources 字段）。