un-comtrade-mcp-server

---

概述

联合国 Comtrade 国际货物和服务贸易统计数据。查询国家和 HS 商品代码，获取双边贸易流和服务贸易数据，并计算贸易差额、贸易伙伴／商品排名及数据可用性。

工具

工具	描述
comtrade_lookup_countries	将国家和地区名称解析为 Comtrade M49 数字代码。
comtrade_search_commodities	按关键词、描述或代码前缀查找 HS 商品代码。
comtrade_list_service_categories	按关键词或父代码列出 EBOPS 2010 服务贸易类别。
comtrade_get_trade_flows	获取双边贸易流记录——每个时期／商品／贸易伙伴对应的价值、数量和重量。
comtrade_get_trade_balance	计算一个或多个时期内某个国家的贸易差额（出口减进口）。
comtrade_get_top_partners	按贸易价值对某个报告国、商品和贸易方向的贸易伙伴进行排名。
comtrade_get_top_commodities	按贸易价值对某个报告国和贸易方向的商品类别进行排名。
comtrade_get_data_availability	检查哪些报告国／时期／分类组合已发布数据。
comtrade_get_services_trade	获取国际服务贸易数据（EBOPS 2010）。

资源

资源	描述
comtrade://countries	完整的国家／地区代码列表，包含 M49 代码、ISO 标识符和报告方有效性。
comtrade://hs-classification/{level}	按章、品目或子目级别划分的 HS 商品顶层层级结构。

这两个资源也可通过工具访问——comtrade_lookup_countries 和 comtrade_search_commodities 可通过关键词搜索相同的数据。

功能参考

comtrade_lookup_countries _工具

• 接受部分或完整的国家名称，或 ISO alpha-2／alpha-3 代码；role 可筛选为 "reporter"、"partner" 或 "any"（默认值）
• 每个匹配项上的 validAsReporter 标志表示有效性——区域分组（例如 World、EU）可作为合作伙伴，但不能作为报告方
• include_groups（默认值为 true）可控制结果中是否包含区域／经济分组
• 参考数据在启动时从 UN 静态文件加载——无需订阅密钥，响应即时返回

---

comtrade_search_commodities _工具

• 支持自由文本关键词、部分描述或代码前缀搜索；classification 可选择 HS（默认的合并数据集）或特定版本 H0–H6
• aggr_level 可限定为 2（章）、4（品目）或 6（子目）；省略则搜索所有级别
• limit 默认值为 50；大于 200 的值将返回所有匹配项。当匹配项超过较小的限制值时，truncated: true
• 每个结果中的 recommendedQueryCode 是适合在贸易查询中作为 cmd_code 传入的最佳代码

---

comtrade_list_service_categories _工具

• 列出 EBOPS 2010 服务类别，可按关键词或 parent_code 筛选
• limit 默认值为 100；大于 500 的值将返回所有类别。当匹配项超过较小的限制值时，truncated: true
• 返回的 id 是 comtrade_get_services_trade 使用的 service_code

---

comtrade_get_trade_flows _工具

• 需要提供 reporter_code、flow_code（M 表示进口／X 表示出口／RX 表示复出口／RM 表示复进口）和 period 值（YYYY 或 YYYYMM）。最多接受 120 个时期，但只处理前 12 个；其余时期会列在 unservedPeriods 中
• partner_code: 0 返回世界总计；省略则按合作伙伴细分。classification 支持 HS、H0–H6 和 SITC S1–S4／SS（商品搜索仅支持 HS）
• cmd_code[] 最多接受 200 个代码并处理前 20 个；其余代码会列在 unservedCmdCodes 中。省略它或传入 ["TOTAL"] 可返回跨商品总计。truncated: true 且带有 truncationHint 表示响应达到 500 条记录的上限；isReported 用于区分直接报告的行与 UN 估算的行

---

comtrade_get_trade_balance _工具

• 按时期返回 balanceUsd（带正负号）、exportsUsd、importsUsd 和 coverageRatio（出口额／进口额）。可选的 cmd_code[] 可将余额限定为 HS 或 SITC 商品
• 每次调用处理 12 个时期和 20 个代码（最多接受 120 个时期和 200 个代码），其余内容会列在 unservedPeriods／unservedCmdCodes 中。如果任一流达到 500 条记录的上限，notice 会发出警告，提示余额可能不完整
• 每个响应中的 mirrorCaveat 都会说明，余额反映的是此报告方自身的数据，而非合作伙伴的镜像数据

---

comtrade_get_top_partners _工具

• 接受一个 reporter_code、一个 flow_code（M／X）和单个 period；可选的单个 cmd_code（省略则返回货物贸易总额）
• 最多返回 limit 个合作伙伴（默认值为 10；大于 50 的值将返回所有已检索结果），每个合作伙伴包含 rank、primaryValueUsd 和 sharePercent
• 获取达到 500 条记录的上限时，truncated: true

---

comtrade_get_top_commodities _工具

• 接受一个 reporter_code、一个 flow_code 和单个 period；aggr_level 为 2（HS 章，默认值）或 4（税目）。partner_code 默认为 World（0）；设置该值可将范围限定为一个贸易伙伴
• 最多返回 limit 个类别（默认值为 10；大于 50 时返回所有已检索结果），每个类别包含 rank、primaryValueUsd 和 sharePercent
• 如果获取数据时达到 500 条记录上限，则返回 truncated: true

---

comtrade_get_data_availability _工具

• 所有筛选条件均为可选项：reporter_code、period、freq（A/M，默认为 A）、type_code（C 代表货物 / S 代表服务，默认为 C）、classification（省略或留空时，货物默认使用 HS，服务默认使用 EB10）
• 在数据集可用的情况下，返回每个数据集的 totalRecords、firstReleased 和 lastReleased；省略所有筛选条件可浏览货物数据的可用情况
• 年度数据通常会在参考年份后的 3–12 个月发布；查询近期时段前请先调用此工具

---

comtrade_get_services_trade _工具

• 输入与 comtrade_get_trade_flows 相同：reporter_code、flow_code（M/X）、period 值，以及可选的 partner_code（0 表示合并所有贸易伙伴）。返回最多 120 个时段中的前 12 个，其余时段列在 unservedPeriods 中
• service_code 用于筛选单个 EBOPS 类别；请使用 comtrade_list_service_categories 查询类别代码
• 如果响应达到 500 条记录上限，则返回 truncated: true 和 truncationHint。国家和时段的覆盖范围比货物数据更有限

---

comtrade://countries _资源

• 完整的国家/地区列表，以 application/json 格式提供，包含 M49 代码、ISO 标识符、validAsReporter 和 isGroup
• 从与 comtrade_lookup_countries 搜索所用的同一启动参考缓存中加载

---

comtrade://hs-classification/{level} _资源

• level 路径参数接受 2（章）、4（税目）或 6（子目）；其他值会触发验证错误
• 返回每个代码的 description、parent 和 isLeaf；完整枚举所有叶节点的内容过大，无法注入——请使用 comtrade_search_commodities 进行关键词搜索

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

Comtrade 专属功能：

• 启动时从联合国静态文件加载参考数据（国家代码、HS 层级、EBOPS 类别）——关键词搜索不会按请求获取数据
• 支持经过身份验证的端点（data/v1/get）和公开预览端点（public/v1/preview）——未设置订阅密钥时，工具会回退到预览端点
• 工作流工具支持并行执行子请求（comtrade_get_trade_balance 会并发获取出口和进口数据）
• 对临时故障采用指数退避重试；如果上游提供了 Retry-After 标头，则遵循该标头
• 描述信息补充——从参考缓存中关联国家和 HS/EBOPS 名称，弥补预览端点未提供 *Desc 字段的问题

便于 Agent 使用的输出：

• 公开预览响应达到 500 条记录时，返回 truncated: true 和恢复提示
• 贸易流记录中的 isReported 标志可区分直接报告的数值与联合国估算或汇总的行
• 国家查询中的 validAsReporter 可避免使用仅限贸易伙伴的地区代码构造无效查询
• 贸易余额输出中的 mirrorCaveat 可直接显示方法论注意事项，无需解析错误文本

入门指南

公共托管实例

可使用公共实例 https://un-comtrade.caseyjhand.com/mcp，无需安装。该实例运行在无密钥公共预览端点上（每次上游请求最多 500 条记录），并将提供的时间段拆分为间隔至少一秒的请求。Balance 每个时间段需要发送两次请求，因此数组越长，耗时越久。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "streamable-http",
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

前提条件： UN Comtrade 订阅密钥为可选项。没有密钥时，工具使用公共预览端点（每次上游请求最多 500 条记录）。密钥用于选择经过身份验证的访问方式；数据检索和请求限制取决于 UN Comtrade 和订阅类型。

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/un-comtrade-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COMTRADE_SUBSCRIPTION_KEY": "your-key-here"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/un-comtrade-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COMTRADE_SUBSCRIPTION_KEY": "your-key-here"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "COMTRADE_SUBSCRIPTION_KEY=your-key-here",
        "ghcr.io/cyanheads/un-comtrade-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 COMTRADE_SUBSCRIPTION_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。开发和 Docker 镜像使用 Bun 1.4.3。
• 可选：UN Comtrade 订阅密钥，用于在订阅限制范围内访问经过身份验证的 API。没有密钥时，数据工具使用公共预览端点（每次上游请求最多 500 条记录）。参考/查询工具（comtrade_lookup_countries、comtrade_search_commodities、comtrade_list_service_categories）无需密钥——它们查询静态 UN 参考文件。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/un-comtrade-mcp-server.git

2. 进入目录：

cd un-comtrade-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set COMTRADE_SUBSCRIPTION_KEY if you have one

配置

所有配置均通过 src/config/server-config.ts 中的 Zod 模式在启动时进行验证。

变量	描述	默认值
COMTRADE_SUBSCRIPTION_KEY	来自 comtradedeveloper.un.org 的 Azure API Management 订阅密钥。没有密钥时，工具使用公共预览端点（最多 500 条记录）。	—
COMTRADE_API_BASE_URL	覆盖 Comtrade API 基础 URL。	https://comtradeapi.un.org
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_PUBLIC_URL	用于反向代理部署的公共源地址覆盖值。	—
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具的参数和结果，按键名进行编辑，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）字节。自由格式值中的机密不会被编辑。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪（/v1/traces）和指标（/v1/metrics）的 OTLP 基础 URL。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	可选的 OTLP 日志端点，按原样使用。	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t un-comtrade-mcp-server .
docker run --rm -e COMTRADE_SUBSCRIPTION_KEY=your-key -p 3010:3010 un-comtrade-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/un-comtrade-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化服务。
src/config	使用 Zod 解析和验证环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含九个工具，涵盖参考数据解析、贸易数据和工作流聚合。
src/mcp-server/resources	资源定义（*.resource.ts）。包含国家列表和 HS 层级资源。
src/services/comtrade-data	ComtradeDataService——支持身份验证和预览的请求构建器，带重试和密钥回退功能。
src/services/comtrade-reference	ComtradeReferenceService——参考数据加载器（国家、HS、EBOPS），提供启动缓存和关键词搜索。
src/services/comtrade-meta	ComtradeMetaService——数据可用性和数据集元数据端点。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，由框架捕获——工具逻辑中不使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段
• 关联参考数据（国家、HS 编码）时，必须从启动缓存中读取，而非按请求获取

数据许可

使用 UN Comtrade 数据时，须遵守 UN Comtrade 许可协议，包括其中关于再分发的条款。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。