Datacommons

@pipeworx/datacommons

来自 Google Data Commons 的全球各地标准化公共统计数据：人口、收入、健康、就业、排放量及数千种其他指标。 每个值都会标明原始发布方（US Census、World Bank、Eurostat、CDC、 BLS 等）。

这是 Pipeworx 的一部分——一个将 AI Agent 连接到 1854+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联、未经其认可，也非由其发布。

工具

• datacommons_find_place(name, place_type?, limit?)：将地点名称转换为 Data Commons 地点 ID（dcids），并返回每个候选项的名称和类型。 “California” + State 会返回 geoId/06。“India”会返回 country/IND。
• datacommons_find_variable(query, limit?)：将自然语言指标转换为统计变量 ID， 并附上匹配分数。“median household income” 会返回 Median_Income_Household。
• datacommons_observation(variable, place, date?, limit?)：查询某个地点的一项 变量。返回最新值（默认）、指定日期的值，或使用 date=all 返回完整 时间序列。响应会附上该值的发布方以及报告该值的其他数据源数量，并提供 最多五个数据源的最新值。
• datacommons_child_places(variable, parent_place, child_type, date?, sort?, limit?)： 查询某个父级地点下所有子级地点的某项变量，并按值排序。可用于查询 所有美国州、德克萨斯州的所有县（geoId/48、County），或 europe 中的所有国家。

地点和变量组合没有数据时会报错，并指出两个 ID。绝不会返回空列表。

身份验证

使用平台密钥（PLATFORM_DATACOMMONS_KEY），也可通过 _apiKey 使用自带密钥， 该密钥会作为 X-API-Key 请求头发送到上游。通过网关调用时，没有密钥的调用方 会使用我们的密钥。直接导入此软件包的用户需要从 https://apikeys.datacommons.org 获取免费的 Data Commons 密钥（可自行申请，无需审批）。如果没有密钥，此软件包 会在发送任何上游请求前拒绝调用，并提示“requires an API key”。

数据来源

• Google Data Commons，即 Data Commons 知识图谱（REST v2）。它汇总了来自 国家和国际发布方的官方统计数据。每个值的 publisher 对象都会标明数据集、 测量方法以及发布方的来源页面。

复用条款：此软件包会针对每个请求实时调用 API，不保留副本。每个值仍受其 原始发布方的条款约束，且每个响应中的 publisher 对象都会链接到该发布方的 来源页面。

给后来者的说明：

• 大多数指标都有多个数据源（“facets”），彼此的数据可能不一致。2024 年，美国 人口数据中，Census PEP 的结果为 340.0M，ACS 5-year survey 的结果为 334.9M。 此软件包采用 Data Commons 自身的排序（取第一个有观测值的 facet），并显示 其他结果，方便调用方了解差异。
• 名称解析采用模糊匹配。“Paris”会优先返回 NUTS 地区 FR101，然后是 大约十几个美国城镇。传入 place_type 可缩小范围。
• 指标解析器始终会返回结果，即使查询毫无意义，因此会回退到主题。此软件包 只保留 StatisticalVariable 匹配项，并在最佳分数低于 0.7 时设置 low_confidence。
• Data Commons 在自己的文档中提供了一个受速率限制的试用密钥。该密钥适合 一次性冒烟测试，不适合用于服务调用方。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "datacommons": {
      "url": "https://gateway.pipeworx.io/datacommons/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/datacommons/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、discover_tools、search_within、remember/recall 和其他网关级工具。因此，你看到的工具数量会多于表中所列：目前，单个工具包端点除了列出该工具包自身的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明确切范围，也是当天准确信息的权威来源。

这是有意为之，并非意外的多路复用。元工具可以让限定范围的连接回答此工具包未涵盖的问题——通过 ask_pipeworx 在整个目录中进行路由——无需再添加第二个 MCP 服务。目前无法挂载不带这些元工具的工具包端点；如果额外的架构定义比路由带来的价值更占上下文，不妨只连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和同一组 1854+ 个数据源。唯一的区别是直接列出的是哪个工具包的工具；无论连接哪个 URL，ask_pipeworx 都能访问所有工具包。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/datacommons_find_place \
  -H 'Content-Type: application/json' \
  -d '{"name":"California","place_type":"State"}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/datacommons_find_place。查找工具包：使用 {"query":"..."} 发送 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需与网关往返通信：

{
  "mcpServers": {
    "datacommons": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-datacommons"]
    }
  }
}

或者直接运行，确认它可以启动：

npx -y @pipeworx/mcp-datacommons

它通过 stdin/stdout 使用 MCP，并响应 initialize/tools/list/tools/call，仅提供此工具包的工具——不包含上述网关连接额外提供的共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以不用直接调用工具，而是用通俗的英语提问——这既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Datacommons data" })

网关会选择合适的工具，并自动填充参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT