Un Comtrade MCP Server

@cyanheads/un-comtrade-mcp-server 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. 9 Tools • 3 Resources

Public Hosted Server: https://un-comtrade.caseyjhand.com/mcp

Overview

International merchandise and services trade statistics from UN Comtrade. Resolve country and HS commodity codes, fetch bilateral trade flows and services trade, and compute balances, partner/commodity rankings, and data availability.

Tools

Resources

Country and HS reference data are also reachable through comtrade_lookup_countries and comtrade_search_commodities. The workflow guide ships with npm, Docker, MCPB, and plugins, and is available over MCP as a skill resource.

Capability reference

comtrade_lookup_countries tool

• Accepts a partial or full country name, or an ISO alpha-2/alpha-3 code; role filters to "reporter", "partner" (only entries in UN's partner-area list), or "any" (default)
• validAsReporter flag on each match — most regional groupings (e.g. World) are partner-only, but some report (e.g. the European Union, 97)
• include_groups (default true) toggles regional/economic groupings in the results
• Each match also pulls in entries sharing its ISO-3 identity, ordered exact ISO match, reporter-valid, current before expired, name, then code; reporter and partner-only area codes remain distinct
• entryEffectiveDate and entryExpiredDate (YYYY-MM-DD) give each entity's validity, so historical entities (e.g. Fed. Rep. of Germany, ...1990) sort after current ones
• Country references load from UN static files at startup — no subscription key required. Rows that fail validation are dropped and logged; startup fails on an empty catalog or when fewer than half a file's rows are valid

comtrade_search_commodities tool

• Free-text keyword, partial description, or code-prefix search; classification (case-insensitive, default HS) selects the current HS reference, an HS edition H0–H6, or SITC SS/S1–S4
• aggr_level uses the selected catalog's native levels: HS chapters/headings/subheadings use 2/4/6; SITC has levels 1–5. Omit for all levels. The HS all-commodities TOTAL is level 0, which no aggr_level filter returns
• limit (default 50) is the page size; totalMatches, shown, and truncated describe the page, and offset with the returned nextOffset continues it
• recommendedQueryCode on each result — the code to pass as cmd_code in trade queries, with the same classification

comtrade_list_service_categories tool

• Lists the combined EB service categories, optionally filtered by keyword or parent_code; numeric and alphabetic codes are distinct entries. parent_code: "200" lists the EB10 and EB02 top levels
• schemes on each category names the EBOPS scheme catalogs that list its code (EB10, EB10S, EB02); it is empty when none does and absent, with a notice, when the scheme catalogs could not be loaded. ebParent carries the parent the combined EB catalog gives a code when it differs from parent (TOTAL for EB10's top-level codes, whose parent is 200)
• limit (default 100) is the page size; totalMatches, shown, and truncated describe the page, and offset with the returned nextOffset continues it
• Returned id is the service_code for comtrade_get_services_trade

comtrade_get_trade_flows tool

• Accepts a scalar reporter_code or an array; omission requires an explicit partner_code. Reporter arrays serve the first 20 distinct codes and disclose the remainder in unservedReporters. Served codes of an array that return no rows are listed in reportersWithoutRecords (referenceStatus, optional suggestedReporterCode; omitted when the response is truncated). A scalar partner-only code with no rows gets a notice naming its reporter-valid counterpart (250 → 251)
• Requires flow_code (M import / X export / RX re-export / RM re-import) and period values, all YYYY or all YYYYMM. freq is optional: it is inferred from the period length, mixed lengths are rejected, and an explicit value must match. Up to 120 periods are accepted; keyless calls serve the first 8 (12 with a subscription key). Periods past the cap, or whose request is rate limited or runs out of time, are listed in unservedPeriods with a notice; if every period fails the call returns rate_limited or deadline_exceeded
• partner_code: 0 returns the World total; omit it for a per-partner breakdown. classification (case-insensitive, default HS) supports HS, H0–H6, and SITC S1–S4/SS. Explicit HS editions require authenticated data access; keyless HS returns as-reported editions, identified by each row's classificationCode
• cmd_code[] accepts up to 200 codes and serves the first 20, listing the rest in unservedCmdCodes; omit it or pass ["TOTAL"] for cross-commodity totals. truncated: true plus truncationHint means the response hit the 500-record cap; isReported separates directly reported rows from UN-estimated ones
• Quantity and alternate quantity retain unit codes/abbreviations and estimation flags where available. UN Comtrade sends 0 for what it does not report, so qty/altQty of 0 with unit code -1, and netWgt/grossWgt/cifvalue/fobvalue of 0 beside a positive primaryValue, are omitted: an absent field means not reported, not zero. A 0 in a real unit stays a measurement

comtrade_get_trade_balance tool

• Returns balanceUsd (signed), exportsUsd, importsUsd, and coverageRatio (exports / imports) per period. Optional cmd_code[] restricts the balance to HS or SITC commodities
• partner_code defaults to World (0); a country code computes the reporter's bilateral balance and is echoed with the partner name. classification is case-insensitive with default HS; freq is optional and inferred from the period length (mixed lengths are rejected; an explicit value must match)
• Accepts up to 120 periods and 200 codes. Keyless calls serve the first 4 periods (two requests each; 12 with a subscription key) and 20 codes, listing the rest in unservedPeriods/unservedCmdCodes; a period is served only when both flows complete, and one whose export or import request is rate limited or runs out of time is listed too. A notice warns when either flow hit the 500-record cap and the balance may be incomplete
• A partner-only reporter code (0 World, 250 Metropolitan France) with no data fails with partner_only_reporter, naming the reporter-valid counterpart when one exists (250 → 251)
• mirrorCaveat on every response: the balance reflects this reporter's own values, not the partner's mirror data

comtrade_get_top_partners tool

• Takes one reporter_code, flow_code (M/X), and single period; optional single cmd_code (omit for total merchandise trade) in the selected classification (case-insensitive, default HS; H0–H6 with a subscription key, SITC S1–S4/SS)
• Infers annual or monthly frequency from the period; monthly values require a calendar month from 01 through 12
• Returns the top limit partners (default 10; any larger value is honored, with no return-all threshold), each with rank, primaryValueUsd, and sharePercent; totalPartners and totalValueUsd cover every partner retrieved, and shares divide by totalValueUsd; classification names the catalog the cmd_code was read in
• truncated: true when the fetch hit the 500-record cap. An empty result for a partner-only reporter code ends its notice with the reporter-valid counterpart (250 → 251)

comtrade_get_top_commodities tool

• Takes one reporter_code, flow_code, and single period; aggr_level is 2 (HS chapter, default) or 4 (heading). partner_code defaults to World (0); set it to scope to one partner
• Infers frequency from period. Fetches matching TOTAL to identif