Access UN Comtrade international merchandise and services trade statistics — country lookups, HS commodity search, bilateral trade flows, balances, rankings, and data availability — via MCP. STDIO or Streamable HTTP.\n
\n\n[](https://github.com/cyanheads/un-comtrade-mcp-server/releases/latest/download/un-comtrade-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=un-comtrade-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdW4tY29tdHJhZGUtbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22un-comtrade-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fun-comtrade-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n> **Note:** The UN Comtrade license agreement (§5) prohibits redistributing data without prior written UN permission. Connect with your own Comtrade subscription key.\n\n---\n\n## Tools\n\n9 tools covering the full UN Comtrade workflow — reference resolution, trade data retrieval, aggregated rankings, and coverage checking:\n\n| Tool | Description |\n|:-----|:------------|\n| `comtrade_lookup_countries` | Resolve country and area names to Comtrade M49 numeric codes. Accepts partial names or ISO alpha-2/alpha-3 codes. Returns matching entries with `validAsReporter` flag — regional groupings are valid partner codes but not reporter codes. |\n| `comtrade_search_commodities` | Find HS commodity codes by keyword, partial description, or code prefix. Returns codes at 2-, 4-, or 6-digit aggregation with descriptions, parent code, leaf status, and a `recommended_query_code` field. |\n| `comtrade_list_service_categories` | List EBOPS 2010 service trade categories — the services-domain equivalent of `comtrade_search_commodities`. Returns codes, descriptions, and parent codes. Filter by keyword or browse from a parent code. |\n| `comtrade_get_trade_flows` | Fetch bilateral trade flow records. Returns `primaryValue` (USD, FOB for exports / CIF for imports), quantity, net weight, and period/commodity/partner metadata per row. Accepts multiple periods and commodity codes in one call. |\n| `comtrade_get_trade_balance` | Compute trade balance (exports minus imports) for a country over one or more periods with optional commodity filter. Fetches export and import totals in parallel; returns signed balance, component values, and coverage ratio. |\n| `comtrade_get_top_partners` | Rank trading partners for a reporter by trade value for a given commodity and flow direction. Returns top N partners sorted by descending value for a single period. |\n| `comtrade_get_top_commodities` | Rank commodity categories for a reporter by trade value for a given flow direction and period. Returns top N HS chapters (2-digit) or headings (4-digit) sorted by descending value. |\n| `comtrade_get_services_trade` | Fetch international trade-in-services data (EBOPS 2010). Same bilateral structure as goods trade: returns flow value, period, and reporter/partner/category metadata. |\n| `comtrade_get_data_availability` | Check which reporter/period/classification combinations have published data before constructing expensive queries. Returns record count and publication date per dataset. |\n\n### `comtrade_lookup_countries`\n\nResolve reporter and partner codes from natural-language names or ISO identifiers.\n\n- Accepts partial country name, ISO alpha-2 (`US`), or ISO alpha-3 (`USA`)\n- `role` filter: `\"reporter\"`, `\"partner\"`, or `\"any\"` — narrows results to only valid reporters or all partner areas\n- `validAsReporter` flag on each result — regional groupings (e.g., `Africa`, `ASEAN`) are valid as partners but cannot be used as `reporter_code`\n- Optional `include_groups` to surface regional aggregate codes\n- Reference data is loaded from UN static files at startup — no key required, instant response\n\n---\n\n### `comtrade_search_commodities`\n\nFind the HS code for any product before querying trade flows.\n\n- Free-text keyword search across HS descriptions (e.g., `\"semiconductors\"`, `\"crude oil\"`)\n- Accepts known code prefixes — `\"8471\"` returns the matching chapter and all descendants\n- Aggregation level control: start with `aggr_level: 2` (chapters) to scope a sector, then narrow to `4` or `6` for specific headings or subheadings\n- `recommended_query_code` field on each result — the best level for downstream `comtrade_get_trade_flows` calls\n- Reference data loaded at startup from UN HS files, covering HS combined and editions H0–H6\n\n---\n\n### `comtrade_get_trade_flows`\n\nFetch bilateral trade records — the primary data retrieval tool.\n\n- `reporter_code` + `flow_code` (`M` import / `X` export / `RX` re-export / `RM` re-import) + `period[]` required\n- `period` accepts annual (`YYYY`) or monthly (`YYYYMM`); pass multiple years as an array for time-series in one request (avoids multiple API calls against the 500-req/day free limit)\n- `partner_code: 0` aggregates across all partners (World total) — no partner lookup needed\n- `cmd_code[]` accepts comma-separated HS codes; omit or use `TOTAL` for cross-commodity totals\n- Free-tier cap: 500 records per call; `truncated: true` + hint when the cap is hit\n- Joins country and commodity descriptions from the in-memory reference cache — preview-endpoint responses omit `*Desc` fields\n\n---\n\n### `comtrade_get_trade_balance`\n\nCompute signed trade balance from parallel export + import fetches.\n\n- Runs export (`flowCode=X`) and import (`flowCode=M`) requests in parallel, then computes locally\n- Returns `balance` (USD, signed), `exports`, `imports`, and `coverageRatio` (exports / imports)\n- Optional `cmd_code` filter for commodity-specific balance (e.g., energy trade balance)\n- Surfaces mirror-asymmetry caveat — the balance reflects values as reported by this country, not the mirror reporter\n\n---\n\n### `comtrade_get_top_partners`\n\nRank trading partners by value for a single period.\n\n- Fetches one record per partner by omitting the partner filter, then sorts locally\n- Joins partner names from the in-memory reference cache\n- `limit` controls N returned (default 10)\n- Answers \"who does Germany mainly export machinery to?\" in one call\n\n---\n\n### `comtrade_get_top_commodities`\n\nRank commodity chapters or headings by value for a single period.\n\n- `aggr_level: 2` for HS chapter ranking (21 sections), `4` for heading ranking\n- Optional `partner_code` to scope the ranking to a specific bilateral relationship\n- Answers \"what does Japan mainly import?\" — symmetric counterpart to `comtrade_get_top_partners`\n\n---\n\n### `comtrade_get_data_availability`\n\nCheck data coverage before querying.\n\n- Accepts optional `reporter_code`, `period`, `freq` (`A` annual / `M` monthly), and `classification` filters\n- Returns dataset records with period, classification, record count, and publication date\n- Annual data is typically published 3–12 months after the reference year — call this before querying recent periods to avoid empty results\n\n---\n\n### `comtrade_get_services_trade`\n\nFetch services trade data (EBOPS 2010 classification).\n\n- Same bilateral structure and parameters as `comtrade_get_trade_flows`\n- `service_code` accepts an EBOPS category code — use `comtrade_list_service_categories` to find the right code\n- Covers financial services, transport, travel, insurance, and all EBOPS 2010 categories\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:-----|:-----|:------------|\n| Resource | `comtrade://countries` | Complete country/area code list — M49 numeric codes, ISO identifiers, `validAsReporter` flag, and group membership. Loaded from UN reference data at startup. |\n| Resource | `comtrade://hs-classification/{level}` | Top-level HS commodity hierarchy at aggregation level `2` (chapters), `4` (headings), or `6` (top ~1 200 subheadings). Full leaf enumeration is too large to inject — use `comtrade_search_commodities` for keyword search. |\n\nAll resource data is also reachable via tools. `comtrade://hs-classification/{level}` provides a browsable hierarchy; for keyword resolution use `comtrade_search_commodities` instead.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nUN Comtrade-specific:\n\n- Reference data (country codes, HS hierarchy, EBOPS categories) loaded at startup from UN static files — fast keyword search with no per-request fetches\n- Authenticated (`data/v1/get`) and public preview (`public/v1/preview`) endpoint support — tools fall back to the preview endpoint when no subscription key is set\n- Parallel sub-request execution for workflow tools (`comtrade_get_trade_balance` runs export + import fetches concurrently)\n- Exponential backoff with retry on 429 responses\n- Description enrichment — joins country names and HS/EBOPS descriptions from the in-memory reference cache before returning results, covering the preview endpoint's omission of `*Desc` fields\n\nAgent-friendly output:\n\n- `truncated: true` + hint on any response where the 500-record free-tier cap was hit — agents know when results are incomplete and can narrow the query\n- `isReported` flag on trade flow records — distinguishes directly reported values from UN-estimated/aggregated rows so agents can reason about data reliability\n- `validAsReporter` on country lookups — prevents agents from constructing invalid queries with partner-only area codes\n- Mirror-asymmetry caveat on trade balance output — agents can surface methodological notes to users without parsing error text\n\n## Getting started\n\n> **Prerequisites:** A [UN Comtrade subscription key](https://comtradedeveloper.un.org/) is optional but recommended. Without one, tools fall back to the public preview endpoint (500 records/call, lower rate limit). With a free-tier key you get the same record cap but higher request headroom.\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"un-comtrade-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/un-comtrade-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"COMTRADE_SUBSCRIPTION_KEY\": \"your-key-here\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"un-comtrade-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/un-comtrade-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"COMTRADE_SUBSCRIPTION_KEY\": \"your-key-here\"\n }\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 COMTRADE_SUBSCRIPTION_KEY=... bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+). Development and Docker images use Bun 1.4.0.\n- Optional: a [UN Comtrade subscription key](https://comtradedeveloper.un.org/) for full API access. Without one, all tools fall back to the public preview endpoint (500 records/call). Reference/lookup tools (`comtrade_lookup_countries`, `comtrade_search_commodities`, `comtrade_list_service_categories`) never require a key — they query static UN reference files.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/un-comtrade-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd un-comtrade-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set COMTRADE_SUBSCRIPTION_KEY if you have one\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `COMTRADE_SUBSCRIPTION_KEY` | Azure API Management subscription key from [comtradedeveloper.un.org](https://comtradedeveloper.un.org). Without it, tools use the public preview endpoint (500-record cap). | — |\n| `COMTRADE_API_BASE_URL` | Override the Comtrade API base URL. | `https://comtradeapi.un.org` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | HTTP server port. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |\n| `MCP_PUBLIC_URL` | Public origin override for reverse-proxy deployments. | — |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t un-comtrade-mcp-server .\ndocker run --rm -e COMTRADE_SUBSCRIPTION_KEY=your-key -p 3010:3010 un-comtrade-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/un-comtrade-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools, resources, and inits services. |\n| `src/config` | Environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Nine tools across reference resolution, trade data, and workflow aggregations. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Country list and HS hierarchy resources. |\n| `src/services/comtrade-data` | `ComtradeDataService` — authenticated/preview request builder with retry and key fallback. |\n| `src/services/comtrade-reference` | `ComtradeReferenceService` — reference data loader (countries, HS, EBOPS), startup cache, keyword search. |\n| `src/services/comtrade-meta` | `ComtradeMetaService` — data availability and dataset metadata endpoints. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n- Reference data (countries, HS codes) joins must pull from the startup cache, not per-request fetches\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE) for details.\n",
"bytes": 17455,
"sha": "ffb8718e0f14b3f308ac9db95ddf0be99e850f0f7fb811a539031e313fd633b7",
"repo_slug": "cyanheads/un-comtrade-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_un_comtrade_mcp_serv_e43f2baf/readme"
}