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

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: