un-comtrade-mcp-server

v0.5.0 pre-1.0

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.

un-comtrade.caseyjhand.com/mcp
claude mcp add --transport http un-comtrade-mcp-server https://un-comtrade.caseyjhand.com/mcp
codex mcp add un-comtrade-mcp-server --url https://un-comtrade.caseyjhand.com/mcp
{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http un-comtrade-mcp-server https://un-comtrade.caseyjhand.com/mcp
{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://un-comtrade.caseyjhand.com/mcp"
      ]
    }
  }
}
{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "http",
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://un-comtrade.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Tools

11

comtrade_lookup_countries

Resolve country and area names to Comtrade M49 numeric codes used in all data queries. Accepts a partial or full name, an official name (e.g. "Republic of Korea"), a common name (e.g. "UK", "Turkey"), or an ISO alpha-2/alpha-3 code (e.g. "USA", "US"), ignoring case and accents; exact matches are listed before partial ones. Returns matching entries with their numeric code, ISO identifiers, a validAsReporter flag, and validity dates; within the exact and partial groups, historical entities such as Fed. Rep. of Germany (...1990) are listed after current ones. World (code 0) is a valid partner but not a valid reporter, while some groupings, such as the European Union (97), do report — check validAsReporter. Use this before any trade data tool that requires reporter_code or partner_code. To aggregate across all partners, use partner code 0 (World) — no lookup needed.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_lookup_countries",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Country or area to find by name, name fragment, official or common name, or ISO alpha-2/alpha-3 code. Case, accents and surrounding spaces are ignored. Name matching treats St and St. as Saint and accepts straight or curly apostrophes. Examples: \"Germany\", \"DEU\", \"DE\", \"south korea\", \"Turkiye\", \"St. Lucia\"."
    },
    "role": {
      "default": "any",
      "description": "Filter by role: \"reporter\" returns only codes valid for reporter_code; \"partner\" returns only codes valid for partner_code, which include World (0) but not reporter-only groupings such as the European Union (97) and ASEAN (975); \"any\" returns every match.",
      "type": "string",
      "enum": [
        "reporter",
        "partner",
        "any"
      ]
    },
    "include_groups": {
      "default": true,
      "description": "Whether to include regional and economic groupings (e.g. EU, ASEAN). Set to false to return only individual countries and groupings under which a match’s goods trade is published (490 Other Asia, nes for 158 Taiwan, Province of China).",
      "type": "boolean"
    }
  },
  "required": [
    "query",
    "role",
    "include_groups"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_search_commodities

Find HS or SITC commodity codes by keyword, description, or code prefix. A code written with dots, spaces, or hyphens ("0901.11") matches 090111. Exact codes, code prefixes and contiguous description matches rank first, followed by descriptions containing every query term in any order. Default HS searches include historical codes and report which edition catalogs list each code. Use a trade row’s classificationCode or comtrade_get_data_availability to identify the edition, then search that edition for its descriptions. Keyless goods queries use HS for as-reported data. Continue with nextOffset using the same query, classification, and aggr_level.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_search_commodities",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Keyword, partial description, or commodity code prefix. Dots, spaces, and hyphens in a code are ignored, so \"0901.11\" finds 090111. Examples: \"motor vehicles\", \"8471\", \"coffee\", \"84\" (HS chapter 84 = machinery)."
    },
    "classification": {
      "default": "HS",
      "description": "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 explicit HS edition, or SS/S1–S4 for SITC.",
      "type": "string",
      "enum": [
        "HS",
        "H0",
        "H1",
        "H2",
        "H3",
        "H4",
        "H5",
        "H6",
        "S1",
        "S2",
        "S3",
        "S4",
        "SS"
      ]
    },
    "aggr_level": {
      "description": "Native aggregation level: HS uses 2 (chapter), 4 (heading), 6 (subheading); SITC uses 1–5. Omit to return all matching levels.",
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        },
        {
          "type": "number",
          "const": 4
        },
        {
          "type": "number",
          "const": 5
        },
        {
          "type": "number",
          "const": 6
        }
      ]
    },
    "limit": {
      "default": 50,
      "description": "Maximum matching codes returned per page; defaults to 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "offset": {
      "default": 0,
      "description": "Number of matching codes to skip; use nextOffset to continue.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query",
    "classification",
    "limit",
    "offset"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_list_service_categories

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). Search by keyword or by several terms in any order, or browse direct children of a parent code; "200" lists the EB10 and EB02 top levels. Use the returned id as service_code in comtrade_get_services_trade. Code 3 is transport; SA is manufacturing services. Each page holds up to limit categories; continue with nextOffset using the same query and parent_code.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_list_service_categories",
    "arguments": {}
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "description": "Description keyword, phrase, whitespace-separated terms, or category code prefix. Description terms match case-insensitively in any order. Codes compare case-insensitively and keep their dots. Examples: \"transport\", \"SA\", \"3.1\", \"insurance pension\". Omit, or leave blank, to list all EB categories.",
      "type": "string"
    },
    "parent_code": {
      "description": "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.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Maximum categories returned per page; defaults to 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "offset": {
      "default": 0,
      "description": "Number of matching categories to skip; use nextOffset to continue.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "limit",
    "offset"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_trade_flows

open-world

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; pass partner_code 0 to get totals aggregated across all partners. Omit cmd_code or pass "TOTAL" to aggregate all commodities. Follow nextOffset for remaining records; each page repeats the upstream period requests. Keyless preview makes one request per served period, at least 4 seconds apart, with a 500-record cap per request. Use comtrade_lookup_countries to resolve reporter/partner codes and comtrade_search_commodities to resolve HS codes. For SITC, supply codes from the selected SITC revision.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_trade_flows",
    "arguments": {
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "default": 25,
      "description": "Records per page (default 25). Larger requests are limited to 1000 with a notice.",
      "type": "integer",
      "minimum": 1
    },
    "offset": {
      "default": 0,
      "description": "Number of retrieved records to skip.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "reporter_code": {
      "description": "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 reportersWithoutRecords. Some codes are partners only (0 World, 250 Metropolitan France, 158 Taiwan, Province of China): France reports as 251, and UN Comtrade publishes the trade of 158 under 490 (Other Asia, nes). Omit only with an explicit partner_code to query all reporters.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 999,
          "description": "One M49 reporter code."
        },
        {
          "minItems": 1,
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 999
          },
          "description": "Reporter codes to query together."
        }
      ]
    },
    "flow_code": {
      "description": "Trade flow direction: M=imports, X=exports, RX=re-exports, RM=re-imports.",
      "type": "string",
      "enum": [
        "M",
        "X",
        "RX",
        "RM"
      ]
    },
    "period": {
      "minItems": 1,
      "maxItems": 120,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$"
      },
      "description": "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 distinct periods keyless (12 with authenticated access); the rest, and any period whose request is rate limited, fails on a UN Comtrade server error or network failure, or runs out of time, are listed in unservedPeriods. Input ceiling 120."
    },
    "partner_code": {
      "description": "M49 code of the trade partner. Use 0 to aggregate across all partners (World total). Omitting it can return World alongside the partner breakdown.",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "cmd_code": {
      "description": "HS or SITC commodity codes to query. Serves the first 20 distinct codes and discloses the remainder; input ceiling 200. Pass [\"TOTAL\"] or omit to aggregate all commodities. Use comtrade_search_commodities for codes in the selected HS or SITC edition.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
      }
    },
    "classification": {
      "default": "HS",
      "description": "Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.",
      "type": "string",
      "enum": [
        "HS",
        "H0",
        "H1",
        "H2",
        "H3",
        "H4",
        "H5",
        "H6",
        "S1",
        "S2",
        "S3",
        "S4",
        "SS"
      ]
    },
    "freq": {
      "description": "Frequency: A=annual YYYY, M=monthly YYYYMM (01–12). Omit to infer it from the periods; an explicit value must match them.",
      "type": "string",
      "enum": [
        "A",
        "M"
      ]
    }
  },
  "required": [
    "limit",
    "offset",
    "flow_code",
    "period",
    "classification"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_trade_balance

open-world

Compute the trade balance for a country over one or more periods — total exports minus total imports — with an optional HS or SITC commodity filter whose codes must not overlap. Keyless preview makes two requests per served period, at least 4 seconds apart; authenticated calls batch periods. Returns the export and import values per period and, when both flows have data, the signed balance (USD) and coverage ratio (exports / imports). Note: mirror asymmetry is common — balance reflects values as reported by this country; the same flow may be recorded differently by the partner. Uses comtrade_lookup_countries to resolve reporter codes.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_trade_balance",
    "arguments": {
      "reporter_code": "<reporter_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reporter_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "description": "M49 numeric code of the reporting country (0–999). A partner-only code (0 World, 250 Metropolitan France, 158 Taiwan, Province of China) with no data fails with partner_only_reporter, naming the code to query instead when one exists: 251 shares the ISO-3 identity of 250, and UN Comtrade publishes the trade of 158 under 490 (Other Asia, nes)."
    },
    "partner_code": {
      "default": 0,
      "description": "M49 partner code (0–999); defaults to World (0). The balance uses the reporter’s values. A partner code with a reporter-valid counterpart (840 → 842, 158 → 490) that returns no data fails with no_data naming that counterpart.",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "period": {
      "minItems": 1,
      "maxItems": 120,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$"
      },
      "description": "Periods, all annual (YYYY) or all monthly (YYYYMM); mixed lengths are rejected. Serves the first 4 distinct periods keyless (12 with authenticated access); the rest, and any period whose export or import request is rate limited, hits a UN Comtrade server error or network failure, or runs out of time, are listed in unservedPeriods. Input ceiling 120."
    },
    "cmd_code": {
      "description": "HS or SITC commodity codes whose values the balance sums; omit for the overall balance across all commodities. Exact duplicates count once. Overlapping codes are rejected because their shared trade would be summed twice: a code beside one of its sub-codes (27 and 2709), TOTAL beside any other entry, or AG<n> beside another AG selector or a code whose length is not n. Serves the first 20 and discloses the remainder; input ceiling 200.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
      }
    },
    "classification": {
      "default": "HS",
      "description": "Goods classification: HS/H0–H6 or SITC S1–S4/SS.",
      "type": "string",
      "enum": [
        "HS",
        "H0",
        "H1",
        "H2",
        "H3",
        "H4",
        "H5",
        "H6",
        "S1",
        "S2",
        "S3",
        "S4",
        "SS"
      ]
    },
    "freq": {
      "description": "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.",
      "type": "string",
      "enum": [
        "A",
        "M"
      ]
    }
  },
  "required": [
    "reporter_code",
    "partner_code",
    "period",
    "classification"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_top_partners

open-world

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 period. Fetches a disaggregated breakdown across all partners then sorts locally. Takes an HS or SITC code in the selected classification; omit cmd_code to rank partners for total trade.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_top_partners",
    "arguments": {
      "reporter_code": "<reporter_code>",
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reporter_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "description": "M49 numeric code of the reporting country (0–999)."
    },
    "flow_code": {
      "description": "Trade flow: M=imports, X=exports.",
      "type": "string",
      "enum": [
        "M",
        "X"
      ]
    },
    "period": {
      "type": "string",
      "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$",
      "description": "Single period: annual YYYY or monthly YYYYMM, month 01–12; frequency is inferred."
    },
    "cmd_code": {
      "description": "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.",
      "type": "string",
      "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
    },
    "classification": {
      "default": "HS",
      "description": "Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.",
      "type": "string",
      "enum": [
        "HS",
        "H0",
        "H1",
        "H2",
        "H3",
        "H4",
        "H5",
        "H6",
        "S1",
        "S2",
        "S3",
        "S4",
        "SS"
      ]
    },
    "limit": {
      "default": 10,
      "description": "Number of top partners to return; totalPartners counts every partner retrieved.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "reporter_code",
    "flow_code",
    "period",
    "classification",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_top_services_partners

open-world

Rank partners of one reporter by trade value for a single annual EBOPS series. Omit service_code for total services, or use comtrade_list_service_categories to find one category. EB serves original reports, while EB10 and EB02 serve converted series. Shares divide by the sum of eligible retrieved partners before the display limit. Read coverageNotice before interpreting the ranking.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_top_services_partners",
    "arguments": {
      "reporter_code": "<reporter_code>",
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reporter_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "description": "M49 numeric code of the reporting area (0–999)."
    },
    "flow_code": {
      "description": "Trade flow: M=imports, X=exports.",
      "type": "string",
      "enum": [
        "M",
        "X"
      ]
    },
    "period": {
      "type": "string",
      "pattern": "^[0-9]{4}$",
      "description": "One annual period, YYYY."
    },
    "service_code": {
      "description": "One EBOPS service code. Omit or pass blank for total services.",
      "type": "string",
      "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
    },
    "classification": {
      "description": "EB for as-reported data (default), or EB10 or EB02 for UN Comtrade’s converted series.",
      "default": "EB",
      "type": "string",
      "enum": [
        "EB",
        "EB10",
        "EB02"
      ]
    },
    "limit": {
      "default": 10,
      "description": "Number of partners to display. Counts and sums precede the display limit.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "reporter_code",
    "flow_code",
    "period",
    "classification",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_top_reporters

open-world

Rank retrieved reporting areas by reported import or export value for one goods code and period. Partner 0 (World) ranks reporters by their trade with all partners. Use a bilateral partner to rank reporters by their trade with that area. Shares use the retrieved reporting areas before the display limit. Use comtrade_get_top_partners to rank the partners of one reporter.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_top_reporters",
    "arguments": {
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "flow_code": {
      "description": "Trade flow: M=imports, X=exports.",
      "type": "string",
      "enum": [
        "M",
        "X"
      ]
    },
    "period": {
      "type": "string",
      "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$",
      "description": "One annual YYYY or monthly YYYYMM period. Frequency is inferred."
    },
    "cmd_code": {
      "description": "One commodity code in the selected HS or SITC classification. Omit or pass TOTAL for total merchandise trade.",
      "type": "string",
      "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
    },
    "classification": {
      "default": "HS",
      "description": "Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.",
      "type": "string",
      "enum": [
        "HS",
        "H0",
        "H1",
        "H2",
        "H3",
        "H4",
        "H5",
        "H6",
        "S1",
        "S2",
        "S3",
        "S4",
        "SS"
      ]
    },
    "partner_code": {
      "default": 0,
      "description": "M49 partner code (0–999). Defaults to World (0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "limit": {
      "default": 10,
      "description": "Maximum reporting areas displayed. Totals cover all eligible retrieved reporting areas.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "flow_code",
    "period",
    "classification",
    "partner_code",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_top_commodities

open-world

Rank HS chapters (2-digit) or headings (4-digit) by trade value for one reporter, flow, and annual or monthly period. Set parent_code and a deeper aggr_level to rank headings or subheadings within one chapter or heading. The tool uses matching TOTAL to identify the HS edition and queries explicit commodity codes in chunks, subdividing capped chunks. Shares use matching TOTAL or the reported parent value for a drill-down. Incomplete coverage returns available categories without ranks or shares and identifies unresolved codes. Defaults to World; optionally select one bilateral partner. Counterpart to comtrade_get_top_partners.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_top_commodities",
    "arguments": {
      "reporter_code": "<reporter_code>",
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reporter_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "description": "M49 numeric code of the reporting country (0–999)."
    },
    "flow_code": {
      "description": "Trade flow: M=imports, X=exports.",
      "type": "string",
      "enum": [
        "M",
        "X"
      ]
    },
    "period": {
      "type": "string",
      "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$",
      "description": "Single period: annual (YYYY) or monthly (YYYYMM, month 01–12)."
    },
    "aggr_level": {
      "default": 2,
      "description": "HS aggregation level: 2 = chapter, 4 = heading, 6 = subheading. Level 6 requires parent_code.",
      "anyOf": [
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 4
        },
        {
          "type": "number",
          "const": 6
        }
      ]
    },
    "parent_code": {
      "description": "Two-digit HS chapter or four-digit heading. Supply a deeper aggr_level. Blank is treated as omitted.",
      "type": "string",
      "pattern": "^(?:[0-9]{2}(?:[0-9]{2})?)?$"
    },
    "partner_code": {
      "description": "M49 partner code (0–999) for a bilateral relationship; omit for World aggregate (0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "limit": {
      "default": 10,
      "description": "Number of top commodity categories to return; totalCommodities counts every category retrieved.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "reporter_code",
    "flow_code",
    "period",
    "aggr_level",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_data_availability

open-world

Check which reporter/period/classification combinations have published data before querying trade. Returns datasets ordered by reporter code, newest period first within each reporter, with classification, record count and release dates where available. Annual data is typically published 3–12 months after the reference year and some reporters skip years. Omit filters to browse the index, 50 rows by default. Continue with nextOffset using the same filters and limit.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_data_availability",
    "arguments": {}
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "description": "Maximum datasets returned per page; defaults to 50.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "offset": {
      "default": 0,
      "description": "Number of matching datasets to skip; use nextOffset to continue.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "reporter_code": {
      "description": "M49 reporter code to check. Omit to browse availability across all reporters.",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "period": {
      "description": "Period to check: YYYY (annual) or YYYYMM (monthly). Omit to see all available periods for the reporter.",
      "type": "string",
      "pattern": "^[0-9]{4}(?:0[1-9]|1[0-2])?$"
    },
    "freq": {
      "description": "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.",
      "type": "string",
      "enum": [
        "A",
        "M"
      ]
    },
    "type_code": {
      "default": "C",
      "description": "Trade type: C=commodities (goods), S=services.",
      "type": "string",
      "enum": [
        "C",
        "S"
      ]
    },
    "classification": {
      "description": "Classification code filter (e.g. \"HS\", \"H6\", \"EB10\"). Omitted or blank defaults to HS for goods and EB10 for services.",
      "type": "string",
      "pattern": "^(?:[A-Z][A-Z0-9]*)?$"
    }
  },
  "required": [
    "limit",
    "offset",
    "type_code"
  ],
  "additionalProperties": false
}
view source ↗

comtrade_get_services_trade

open-world

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 classification and whether it is original or converted. Same bilateral structure as goods trade: returns flow value in USD, period, and reporter/partner/category metadata for each row. Follow nextOffset for remaining records; each page repeats the upstream period requests. Use comtrade_list_service_categories to find a service code and its scheme before querying. Keyless preview makes one request per served period, at least 4 seconds apart, capped at 500 records per request. Services coverage is more limited than goods trade.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comtrade_get_services_trade",
    "arguments": {
      "reporter_code": "<reporter_code>",
      "flow_code": "<flow_code>",
      "period": "<period>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "default": 25,
      "description": "Records per page (default 25). Larger requests are limited to 1000 with a notice.",
      "type": "integer",
      "minimum": 1
    },
    "offset": {
      "default": 0,
      "description": "Number of retrieved records to skip.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "reporter_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "description": "M49 numeric code of the reporting country (0–999)."
    },
    "flow_code": {
      "description": "Trade flow: M=imports (debits), X=exports (credits).",
      "type": "string",
      "enum": [
        "M",
        "X"
      ]
    },
    "period": {
      "minItems": 1,
      "maxItems": 120,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{4}$"
      },
      "description": "Annual periods YYYY. Serves the first 8 distinct periods keyless (12 with authenticated access); the rest, and any period whose request is rate limited, fails on a UN Comtrade server error or network failure, or runs out of time, are listed in unservedPeriods. Input ceiling 120."
    },
    "partner_code": {
      "description": "M49 partner code. Use 0 for all partners combined (World). Omitting it can return World alongside the partner breakdown.",
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "service_code": {
      "description": "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_service_categories lists codes with their schemes. Omit to get every category the reporter reported, at mixed levels: totals (200 for EB10 and EB02, S for EB10S) beside their components, so do not sum the rows.",
      "type": "string",
      "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
    },
    "classification": {
      "description": "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 that one; reports made in it stay under EB. EB10S has no converted series; its rows are served only under EB. Case-insensitive; blank means EB.",
      "default": "EB",
      "type": "string",
      "enum": [
        "EB",
        "EB10",
        "EB02"
      ]
    }
  },
  "required": [
    "limit",
    "offset",
    "reporter_code",
    "flow_code",
    "period",
    "classification"
  ],
  "additionalProperties": false
}
view source ↗

Resources

2

Complete list of all Comtrade country and area codes — both reporters and partners — with M49 numeric codes, ISO identifiers, validAsReporter flag, group membership, and entity validity dates. Bundled from reference data loaded at startup. Use comtrade_lookup_countries for name-based search; use this resource to enumerate the full list.

uri comtrade://countries mime application/json

Combined HS discovery hierarchy at level 2 (chapters), 4 (headings), or 6 (subheadings), including historical codes. Edition tags name the H0–H6 catalogs that list a code. Use comtrade_search_commodities for edition-specific descriptions or keyword search.

uri comtrade://hs-classification/{level} mime application/json

Extensions

1

io.modelcontextprotocol/skills

{
  "directoryRead": true
}