@cyanheads/un-comtrade-mcp-server

Note: The UN Comtrade license agreement (§5) prohibits redistributing data without prior written UN permission. Connect with your own Comtrade subscription key.

Tools

9 tools covering the full UN Comtrade workflow — reference resolution, trade data retrieval, aggregated rankings, and coverage checking:

comtrade_lookup_countries

Resolve reporter and partner codes from natural-language names or ISO identifiers.

• Accepts partial country name, ISO alpha-2 (US), or ISO alpha-3 (USA)

• role filter: "reporter", "partner", or "any" — narrows results to only valid reporters or all partner areas

• validAsReporter flag on each result — regional groupings (e.g., Africa, ASEAN) are valid as partners but cannot be used as reporter_code

• Optional include_groups to surface regional aggregate codes

• Reference data is loaded from UN static files at startup — no key required, instant response

comtrade_search_commodities

Find the HS code for any product before querying trade flows.

• Free-text keyword search across HS descriptions (e.g., "semiconductors", "crude oil")

• Accepts known code prefixes — "8471" returns the matching chapter and all descendants

• Aggregation level control: start with aggr_level: 2 (chapters) to scope a sector, then narrow to 4 or 6 for specific headings or subheadings

• recommended_query_code field on each result — the best level for downstream comtrade_get_trade_flows calls

• Reference data loaded at startup from UN HS files, covering HS combined and editions H0–H6

comtrade_get_trade_flows

Fetch bilateral trade records — the primary data retrieval tool.

• reporter_code + flow_code (M import / X export / RX re-export / RM re-import) + period[] required

• 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)

• partner_code: 0 aggregates across all partners (World total) — no partner lookup needed

• cmd_code[] accepts comma-separated HS codes; omit or use TOTAL for cross-commodity totals

• Free-tier cap: 500 records per call; truncated: true + hint when the cap is hit

• Joins country and commodity descriptions from the in-memory reference cache — preview-endpoint responses omit *Desc fields

comtrade_get_trade_balance

Compute signed trade balance from parallel export + import fetches.

• Runs export (flowCode=X) and import (flowCode=M) requests in parallel, then computes locally

• Returns balance (USD, signed), exports, imports, and coverageRatio (exports / imports)

• Optional cmd_code filter for commodity-specific balance (e.g., energy trade balance)

• Surfaces mirror-asymmetry caveat — the balance reflects values as reported by this country, not the mirror reporter

comtrade_get_top_partners

Rank trading partners by value for a single period.

• Fetches one record per partner by omitting the partner filter, then sorts locally

• Joins partner names from the in-memory reference cache

• limit controls N returned (default 10)

• Answers "who does Germany mainly export machinery to?" in one call

comtrade_get_top_commodities

Rank commodity chapters or headings by value for a single period.

• aggr_level: 2 for HS chapter ranking (21 sections), 4 for heading ranking

• Optional partner_code to scope the ranking to a specific bilateral relationship

• Answers "what does Japan mainly import?" — symmetric counterpart to comtrade_get_top_partners

comtrade_get_data_availability

Check data coverage before querying.

• Accepts optional reporter_code, period, freq (A annual / M monthly), and classification filters

• Returns dataset records with period, classification, record count, and publication date

• Annual data is typically published 3–12 months after the reference year — call this before querying recent periods to avoid empty results

comtrade_get_services_trade

Fetch services trade data (EBOPS 2010 classification).

• Same bilateral structure and parameters as comtrade_get_trade_flows

• service_code accepts an EBOPS category code — use comtrade_list_service_categories to find the right code

• Covers financial services, transport, travel, insurance, and all EBOPS 2010 categories

Related MCP server: supply-chain-mcp-server

Resources and prompts

All resource data is also reachable via tools. comtrade://hs-classification/{level} provides a browsable hierarchy; for keyword resolution use comtrade_search_commodities instead.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

UN Comtrade-specific:

• Reference data (country codes, HS hierarchy, EBOPS categories) loaded at startup from UN static files — fast keyword search with no per-request fetches

• 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

• Parallel sub-request execution for workflow tools (comtrade_get_trade_balance runs export + import fetches concurrently)

• Exponential backoff with retry on 429 responses

• 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

Agent-friendly output:

• 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

• isReported flag on trade flow records — distinguishes directly reported values from UN-estimated/aggregated rows so agents can reason about data reliability

• validAsReporter on country lookups — prevents agents from constructing invalid queries with partner-only area codes

• Mirror-asymmetry caveat on trade balance output — agents can surface methodological notes to users without parsing error text

Getting started

Prerequisites: A UN Comtrade subscription key 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.

Add the following to your MCP client configuration file.

{
  "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"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "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"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).

• Optional: a UN Comtrade subscription key 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.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd un-comtrade-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

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

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

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

• Run checks and tests:

  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

The 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.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

• Reference data (countries, HS codes) joins must pull from the startup cache, not per-request fetches

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.