Comtrade

联合国 Comtrade——双边贸易统计

联合国统计司的商品贸易数据库。涵盖每个报告国与每个伙伴国之间的双边贸易流，按商品（HS 编码）细分，数据可追溯数十年。它是国家层面“谁向谁出口什么”的标准数据来源。

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

这对 AI Agent 为什么重要

如果 Agent 要回答任何有关国际贸易的问题——双边关系、商品流、关税背景、供应链集中度——Comtrade 就是数据来源。这些数据采用结构化格式（HS 编码），并在各国之间经过协调，因此跨国比较可靠。

常见工作流：

• 双边分析。“2024 年美中贸易流。”→ comtrade_trade_data({reporter_code: "842", partner_code: "156", year: "2024"}) → 进口额 + 出口额 + 贸易差额。
• 主要商品。“美国从中国进口最多的是什么？”→ comtrade_top_commodities({reporter_code, partner_code, flow: "M"})。
• 主要伙伴。“谁是美国半导体的主要买家？”→ comtrade_top_partners({reporter_code, hs_code: "8542", flow: "X"})。
• **国家代码查询。**ISO 三位数字代码——comtrade_country_codes 会返回完整映射。

由 trade_bilateral_analysis 和 trade_country_profile 组合使用。

身份验证

Comtrade 提供免费和高级套餐。免费套餐的请求频率限制很严格（每分钟仅几次请求）。如需更高调用量，请在 https://comtradeplus.un.org 注册，并通过 _apiKey 传入 API 密钥。

国家和商品代码

类型	格式	示例
国家	ISO 3166-1 数字代码	842（美国）、156（中国）、484（墨西哥）
商品	HS 章／品目／子目	85（电气产品）、8517（电话机）、851712（智能手机）
流向	M / X / 再进口 / 再出口	M = 进口，X = 出口

comtrade_country_codes 会返回完整映射。大多数 Agent 会传入三位数字代码，以避免名称消歧问题。

更新频率

Comtrade 发布数据时会有较长延迟，通常在日历年结束后 6–12 个月。通常可查询的最新年份是上一个日历年。由于数据一经发布基本保持不变，Pipeworx 会将其缓存 30 天。

常见问题

• **报告方与伙伴方的镜像数据。**贸易双方都会报告贸易数据（美国报告从中国进口；中国报告对美国出口）。数据不会完全一致——估值方法（CIF 与 FOB）、运输处理方式和分类存在差异。通常以报告方数据为准；如需两方数据，请分别请求。
• **HS 修订变化。**HS 分类每 5 年更新一次（HS17、HS22 等）。长期时间序列会跨越修订版本；同一商品的代码可能发生变化。Comtrade 会在标准查询中为你进行协调。
• **不包含服务贸易。**Comtrade 仅涵盖货物。服务贸易数据另见 BEA / WTO 数据。不要将二者混为一谈。
• **再出口。**香港对美国的“出口”中包含大量原产于中国的商品再出口。flow 参数可以区分流向；请明确使用。
• **货币。**默认值以 USD 计，但请检查 unit 字段。有些序列仅报告数量（kg、件数），不报告金额。
• **未报告的贸易组合。**并非每个国家每年都会向 Comtrade 报告数据。古巴、伊朗、朝鲜存在较大数据缺口。可以查询伙伴国报告的与该国贸易数据，以补全缺失部分。

快速入门

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

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

此端点实际提供的内容

https://gateway.pipeworx.io/comtrade/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 都会访问同一个网关和相同的 1875+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论连接哪个，ask_pipeworx 都能访问所有工具包的工具。

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

curl -X POST https://gateway.pipeworx.io/v1/tools/comtrade_trade_data \
  -H 'Content-Type: application/json' \
  -d '{"reporter_code":"842","partner_code":"156","year":"2024"}'

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

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

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

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

或者直接运行，以确认服务能够启动：

npx -y @pipeworx/mcp-comtrade

它通过 stdin/stdout 使用 MCP 协议，并针对仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接额外提供的任何共享元工具。代码相同，工具相同，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

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

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

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT