Un Comtrade Mcp Server

cyanheads/un-comtrade-mcp-server

Connects Claude to the UN Comtrade database for querying international merchandise and services trade statistics. Nine tools cover the full workflow: resolve country names to M49 codes, search HS commodity classifications by keyword, fetch bilateral trade flows with partner and commodity breakdowns, compute trade balances, rank top partners or commodities by value, and check data availability before expensive queries. Free tier allows 500 records per call and 500 requests per day, so you'll want to use the aggregation and filtering options carefully. Requires your own UN Comtrade subscription key. Reach for this when building trade analysis workflows, export/import dashboards, or policy research tools that need structured access to official trade statistics without scraping Excel files.

GitHub stars: 4
tools: 9
transport: STDIO, HTTP
env vars: 7
last updated: Nov 11, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://un-comtrade.caseyjhand.com/mcp --name un-comtrade

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http un-comtrade https://un-comtrade.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 9 tools

Verified live against the running server on Nov 6, 2026.

comtrade_lookup_countriesResolve country and area names to Comtrade M49 numeric codes used in all data queries. Accepts a partial name, full name, or ISO alpha-2/alpha-3 code (e.g. "United States", "USA", "US"). Returns matching entries with their numeric code, ISO identifiers, a validAsReporter flag,...3 params

Resolve country and area names to Comtrade M49 numeric codes used in all data queries. Accepts a partial name, full name, or ISO alpha-2/alpha-3 code (e.g. "United States", "USA", "US"). Returns matching entries with their numeric code, ISO identifiers, a validAsReporter flag,...

Parameters* required

include_groupsboolean

Whether to include regional and economic groupings (e.g. EU, ASEAN). Set to false to return only individual countries.default: true

query*string

Country or area name fragment, full name, or ISO alpha-2/alpha-3 code to search for. Case-insensitive. Examples: "Germany", "DEU", "DE", "united states", "china".

rolestring

Filter by role: "reporter" returns only codes valid for the reporterCode parameter, "partner" returns only partner areas (includes regional groupings), "any" returns all matches regardless of role.one of reporter · partner · anydefault: any

comtrade_search_commoditiesFind HS or SITC commodity codes by keyword, partial description, or code prefix in the selected classification. Returns descriptions, native aggregation levels, parents, leaf status, and recommendedQueryCode for subsequent trade queries. HS uses levels 2 (chapter), 4 (heading)...5 params

Find HS or SITC commodity codes by keyword, partial description, or code prefix in the selected classification. Returns descriptions, native aggregation levels, parents, leaf status, and recommendedQueryCode for subsequent trade queries. HS uses levels 2 (chapter), 4 (heading)...

Parameters* required

aggr_levelvalue

Native aggregation level: HS uses 2 (chapter), 4 (heading), 6 (subheading); SITC uses 1–5. Omit to return all matching levels.

classificationstring

Goods reference catalog, case-insensitive: HS uses the default HS.json discovery catalog, whose total identifies H6; it is not an authoritative historical-edition reference. Select H0–H6 for an exp...default: HS

limitinteger

Maximum matching codes returned per page; defaults to 50.default: 50

offsetinteger

Number of matching codes to skip; use nextOffset to continue.default: 0

query*string

Keyword, partial description, or commodity code prefix. Examples: "motor vehicles", "8471", "coffee", "84" (HS chapter 84 = machinery).

comtrade_list_service_categoriesList service trade categories from the combined EB catalog, including numeric EBOPS and SDMX codes. Returns category codes, descriptions, parent codes, and the EBOPS scheme catalogs that list each code: EB10 (EBOPS 2010), EB10S (EBOPS 2010 SDMX codes), EB02 (EBOPS 2002). Filte...4 params

List service trade categories from the combined EB catalog, including numeric EBOPS and SDMX codes. Returns category codes, descriptions, parent codes, and the EBOPS scheme catalogs that list each code: EB10 (EBOPS 2010), EB10S (EBOPS 2010 SDMX codes), EB02 (EBOPS 2002). Filte...

Parameters* required

limitinteger

Maximum categories returned per page; defaults to 100.default: 100

offsetinteger

Number of matching categories to skip; use nextOffset to continue.default: 0

parent_codestring

Return direct children of this EB category code. Examples: "3" for transport sub-categories, "3.1" for sea transport sub-categories, or "200" for the EB10 and EB02 top-level categories.

querystring

Keyword or category code prefix to filter results. Examples: "transport", "SA", "financial services". Omit to list all EB categories.

comtrade_get_trade_flowsFetch bilateral trade flow records — the primary data retrieval tool. Returns trade value in USD (primaryValue — FOB for exports, CIF for imports), quantity, net weight, and period/commodity/partner metadata for each row. Accepts multiple periods and commodity codes per call;...7 params

Fetch bilateral trade flow records — the primary data retrieval tool. Returns trade value in USD (primaryValue — FOB for exports, CIF for imports), quantity, net weight, and period/commodity/partner metadata for each row. Accepts multiple periods and commodity codes per call;...

Parameters* required

classificationstring

Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.default: HS

cmd_codearray

HS or SITC commodity codes to query. Serves the first 20 codes and discloses the remainder; input ceiling 200. Pass ["TOTAL"] or omit to aggregate all commodities. Use comtrade_search_commodities f...

flow_code*string

Trade flow direction: M=imports, X=exports, RX=re-exports, RM=re-imports.

freqstring

Frequency: A=annual YYYY, M=monthly YYYYMM (01–12). Omit to infer it from the periods; an explicit value must match them.

partner_codeinteger

M49 code of the trade partner. Use 0 to aggregate across all partners (World total). Omit to get a disaggregated breakdown by partner country.

period*array

One or more periods to query, all annual "YYYY" (e.g. ["2022", "2023"]) or all monthly "YYYYMM" (e.g. ["202201", "202202"]); mixed lengths are rejected. Serves the first 8 periods keyless (12 with...

reporter_codevalue

M49 reporter code or nonempty array (input ceiling 200). Deduplicates and serves the first 20 reporters, disclosing the remainder; served codes of an array that return no records are listed in repo...

comtrade_get_trade_balanceCompute the trade balance for a country over one or more periods — total exports minus total imports — with optional HS or SITC commodity filter. Keyless preview makes two requests per served period, at least 4 seconds apart; authenticated calls batch periods. Returns the sign...6 params

Compute the trade balance for a country over one or more periods — total exports minus total imports — with optional HS or SITC commodity filter. Keyless preview makes two requests per served period, at least 4 seconds apart; authenticated calls batch periods. Returns the sign...

Parameters* required

classificationstring

Goods classification: HS/H0–H6 or SITC S1–S4/SS.default: HS

cmd_codearray

HS or SITC commodity codes to restrict the balance calculation. Serves the first 20 and discloses the remainder; input ceiling 200. Omit to compute the overall trade balance across all commodities.

freqstring

Frequency for both flows: A=annual YYYY, M=monthly YYYYMM (01–12). Omit to infer it from the periods; an explicit value must match them.

partner_codeinteger

M49 partner code (0–999); defaults to World (0). The balance uses the reporter’s values.default: 0

period*array

Periods, all annual (YYYY) or all monthly (YYYYMM); mixed lengths are rejected. Serves the first 4 keyless (12 with authenticated access); the rest, and any period whose export or import request is...

reporter_code*integer

M49 numeric code of the reporting country (0–999). A partner-only code (0 World, 250 Metropolitan France) with no data fails with partner_only_reporter, naming the reporter-valid code when one exis...

comtrade_get_top_partnersRank trading partners for a reporter by trade value for a given commodity and flow direction. Returns the top N partners sorted by descending value — answers "who does country X mainly export product Y to?" or "where does country X mainly import product Z from?" for a single p...6 params

Rank trading partners for a reporter by trade value for a given commodity and flow direction. Returns the top N partners sorted by descending value — answers "who does country X mainly export product Y to?" or "where does country X mainly import product Z from?" for a single p...

Parameters* required

classificationstring

Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.default: HS

cmd_codestring

Single goods code in the selected classification: HS (e.g. "84", "8471") or SITC (e.g. "071"). Omit or pass "TOTAL" to rank partners for total merchandise trade.

flow_code*string

Trade flow: M=imports, X=exports.

limitinteger

Number of top partners to return; totalPartners counts every partner retrieved.default: 10

period*string

Single period: annual YYYY or monthly YYYYMM, month 01–12; frequency is inferred.

reporter_code*integer

M49 numeric code of the reporting country (0–999).

comtrade_get_top_commoditiesRank HS chapters (2-digit) or headings (4-digit) by trade value for one reporter, flow, and annual or monthly period. Retrieves matching TOTAL and the reporter’s HS edition, then queries explicit commodity codes in chunks; capped chunks are subdivided. Shares use matching TOTA...6 params

Rank HS chapters (2-digit) or headings (4-digit) by trade value for one reporter, flow, and annual or monthly period. Retrieves matching TOTAL and the reporter’s HS edition, then queries explicit commodity codes in chunks; capped chunks are subdivided. Shares use matching TOTA...

Parameters* required

aggr_levelvalue

HS aggregation level: 2 = chapter (broader), 4 = heading (more specific).default: 2

flow_code*string

Trade flow: M=imports, X=exports.

limitinteger

Number of top commodity categories to return; totalCommodities counts every category retrieved.default: 10

partner_codeinteger

M49 partner code (0–999) for a bilateral relationship; omit for World aggregate (0).

period*string

Single period: annual (YYYY) or monthly (YYYYMM, month 01–12).

reporter_code*integer

M49 numeric code of the reporting country (0–999).

comtrade_get_data_availabilityCheck which reporter/period/classification combinations have published data before constructing expensive trade queries. Returns dataset records with period, classification, record count, and first/latest release dates. Call this before querying recent periods — annual data is...7 params

Check which reporter/period/classification combinations have published data before constructing expensive trade queries. Returns dataset records with period, classification, record count, and first/latest release dates. Call this before querying recent periods — annual data is...

Parameters* required

classificationstring

Classification code filter (e.g. "HS", "H6", "EB10"). Omitted or blank defaults to HS for goods and EB10 for services.

freqstring

Frequency: A=annual YYYY, M=monthly YYYYMM (01–12). Omit to infer it from period, or annual when period is omitted too; an explicit value must match period.

limitinteger

Maximum datasets returned per page; defaults to 50.default: 50

offsetinteger

Number of matching datasets to skip; use nextOffset to continue.default: 0

periodstring

Period to check: YYYY (annual) or YYYYMM (monthly). Omit to see all available periods for the reporter.

reporter_codeinteger

M49 reporter code to check. Omit to browse availability across all reporters.

type_codestring

Trade type: C=commodities (goods), S=services.default: C

comtrade_get_services_tradeFetch annual international trade-in-services data. Classification EB (default) serves each reporter-period as reported, in its own scheme (EB10, EB10S or EB02 codes); EB10 or EB02 selects UN Comtrade's conversion of other schemes into that one. Each row names its classificatio...6 params

Fetch annual international trade-in-services data. Classification EB (default) serves each reporter-period as reported, in its own scheme (EB10, EB10S or EB02 codes); EB10 or EB02 selects UN Comtrade's conversion of other schemes into that one. Each row names its classificatio...

Parameters* required

classificationstring

Services classification. EB (default): each reporter-period as reported, in its own scheme (EB10, EB10S or EB02 codes). EB10 or EB02: UN Comtrade's conversion of reports from other schemes into tha...one of EB · EB10 · EB02default: EB

flow_code*string

Trade flow: M=imports (debits), X=exports (credits).

partner_codeinteger

M49 partner code. Use 0 for all partners combined. Omit for a disaggregated by-partner breakdown.

period*array

Annual periods YYYY. Serves the first 8 keyless (12 with authenticated access); the rest, and any period whose request is rate limited or runs out of time, are listed in unservedPeriods. Input ceil...

reporter_code*integer

M49 numeric code of the reporting country (0–999).

service_codestring

Service category code in one scheme: "7" (EB10), "SG" (EB10S) and "260" (EB02) are each financial services. Under EB a code returns rows only for periods reported in its scheme; comtrade_list_servi...

Configuration

COMTRADE_SUBSCRIPTION_KEY

Azure API Management key from comtradedeveloper.un.org. Optional — without it, tools fall back to the public preview endpoint (500-record cap).

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Readme

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

10 Tools • 3 Resources

View the full README on GitHub

Details

Repository: github.com/cyanheads/un-comtrade-mcp-server
Package: @cyanheads/un-comtrade-mcp-server
Transport: STDIO, HTTP
Registry: MCP registry, active
Resources: 5
Tools verified: Nov 6, 2026

Un Comtrade Mcp Server

Install

Tools

Configuration

Readme

@cyanheads/un-comtrade-mcp-server

Details

More from cyanheads