comtrade
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
xippios-comtrade
Typed Python client, MCP server and FastAPI routes for UN Comtrade, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).
Install
uv add xippios-comtrade # client only
uv add "xippios-comtrade[mcp]" # + MCP server
uv add "xippios-comtrade[http]" # + FastAPI routerSet COMTRADE_API_KEY in the environment. Nothing is read from files. The public
operations (get_comtrade_releases, get_world_share) and the reference files need no
key and send none.
Related MCP server: @cyanheads/un-comtrade-mcp-server
30-second example
from xippios.comtrade import get_counts, get_data
# Switzerland (reporter 757) exports to the World (partner 0) in 2023, all products.
query = {
"reporter_code": "757",
"partner_code": "0",
"period": "2023",
"cmd_code": "TOTAL",
"flow_code": "X",
}
get_counts("C", "A", "HS", **query).data # 32: every customs procedure and mode of transport
result = get_data("C", "A", "HS", **query)
total = next(r for r in result.data if (r.customs_code, r.mot_code) == ("C00", 0))
total.primary_value # Decimal('419922543423.509'); JSON: a number
result.meta.endpoint, result.meta.request # 'data/v1/get', the arguments aboveParameters are upstream's (typeCode, reporterCode, ...) in snake_case and take
upstream's codes, several of them comma-separated as upstream takes them ("757,842").
Reporter and partner codes are UN Comtrade's, not ISO numeric: Switzerland is 757.
Every argument is checked before the call: coded ones (type_code, cl_code,
flow_code, customs_code, mot_code, aggregate_by, breakdown_mode) against
the lists packaged from upstream's reference files and spec (xippios.comtrade.enums;
list_codes gives each value with upstream's words for it),
reporter_code against the packaged copy of upstream's Reporters.json
(reference/Reporters.json) and partner_code and partner2_code against that of
partnerAreas.json, the others by shape. An unknown area, customs or transport code
raises UnknownCode, an InvalidRequestError naming the packaged list, its fetch date
and the closest code (756 names 757, Switzerland; C16 names C15, Relief
consignments); any other mistake raises InvalidRequestError naming the closest valid
value.
from xippios.comtrade import (
list_classifications,
list_codes,
list_commodities,
list_partners,
list_reporters,
)
list_reporters().data # 255 reporters, packaged with this version: no call
list_reporters(search="switz").data # code, ISO alpha-3 or name, any case: 757
list_partners().data # 310 partner areas, 0 World among them
list_commodities("HS", search="coffee").data # from 8,262 HS codes, fetched keyless once
list_codes("motCode").data[3] # MotCodeValue(mot_code='2100', text='Sea'): packaged
list_classifications("cmd:H6").data[0].variable # 'Product [HS 2022]': upstream's indexFour task-shaped slices on data/v1/get answer the common questions in one call each
(the series in one call per 12 periods), at the total of every breakdown, one row per
reporter × partner × product code × period. Areas are UN Comtrade's codes or ISO alpha-3
codes; YYYY periods ask for annual data, YYYYMM for monthly:
from xippios.comtrade import (
get_bilateral_flows,
get_commodity_series,
get_top_partners,
get_world_trade,
)
get_bilateral_flows("CHE", "USA", "TOTAL,27", "2022,2023", "X").data # 4 rows
years = ",".join(str(year) for year in range(2010, 2024))
get_commodity_series("757", "27", "X", years).data # 14 years, two calls, by period
get_world_trade("27", "2023", "M").data[0].reporter_desc # 'China': largest first
[r.partner_desc for r in get_top_partners("CHE", "TOTAL", "2023", "X", 3).data]
# ['USA', 'Germany', 'China']: World, the total, is droppedRelease dates are per dataset, so they sit on the rows, not in meta.published_at.
Upstream prints first_released, last_released, publication_date and date_release
without a zone, so they are naive datetimes:
from xippios.comtrade import (
get_comtrade_releases,
get_data_availability,
get_live_update,
get_metadata,
get_world_share,
)
[dataset] = get_data_availability("C", "A", "HS", reporter_code="757", period="2023").data
dataset.first_released, dataset.last_released # first publication and latest revision
notes = get_metadata("C", "A", "HS", reporter_code="757", period="2023").data[0].notes
[note.publication_date for note in notes] # "New Data", then each "Revised Data"
get_live_update().data # the 50 most recent releases, newest first
get_comtrade_releases().data # upstream's recent releases (newest first when recorded); keyless
[share] = get_world_share("C", "A", period="2023", reporter_code="757").data # keyless
share.world_share, share.last_released # Decimal('0.01651852126450239'), its releaseTwo Tools operations, which upstream's spec marks "EXPERIMENTAL - USE SPARINGLY", put exports beside imports and a reporter's figures beside its partners' mirror figures:
from xippios.comtrade import get_bilateral_data, get_trade_balance
ch = {"reporter_code": "757", "period": "2023", "cmd_code": "TOTAL"}
[row] = get_trade_balance("C", "A", "HS", partner_code="0", breakdown_mode="classic", **ch).data
row.primary_value_x, row.primary_value_m # Switzerland's 2023 exports and imports
row.primary_value_bal # upstream's "X - M", as sent
bilateral = get_bilateral_data("C", "A", "HS", partner_code="842", flow_code="X", **ch).data
bilateral.note # upstream's data-gap note: 'EXPERIMENTAL: We have good news! ...'
[row] = bilateral.data
row.primary_value, row.mirror_primary_value # exports to the USA; the USA's importsBoth need reporter_code or partner_code, and cmd_code, since upstream offers no
count to check a query's size first. A mirror of 0 is no sign of no trade: the mirror
depends on whether the partner reported. So get_bilateral_data returns upstream's
note, which counts the partners with a data gap without naming them, and its
timestamp_requested, with the rows: its data is one BilateralData, not a list.
A fifth slice, get_mirror_flows, asks getBilateralData the slices' way: one reporter and
one partner as codes or ISO alpha-3, single product codes, up to 12 periods of one
format, one flow. Each row holds the reporter's figures beside the partner's mirror of
them, and the result keeps the note:
from xippios.comtrade import get_mirror_flows
mirror = get_mirror_flows("CHE", "USA", "27", "2022,2023", "X").data
mirror.note # 'EXPERIMENTAL: We have good news! There is no data gap ...'
[(r.period, r.primary_value, r.mirror_primary_value) for r in mirror.data]
# Switzerland's chapter 27 exports to the USA beside the USA's reported imports of themget_data counts first with upstream's countOnly: a count of zero returns an empty
result without a second call, and a count above 100,000 raises QueryTooLarge with the
count before anything is fetched, because upstream would cut the answer at 100,000 rows
without saying so. A free key allows 1 call per second and 500 calls per day, and
countOnly calls count; the client spaces calls 1.5 s apart (upstream's gateway refuses
some calls spaced exactly 1 s apart) and counts no calls, so the daily quota is yours to
track: once upstream answers that it is spent, the client sends nothing more until the
time upstream names and raises RateLimitError instead.
MCP
{
"mcpServers": {
"comtrade": {
"command": "uvx",
"args": ["--from", "xippios-comtrade[mcp]", "xippios-comtrade-mcp"],
"env": { "COMTRADE_API_KEY": "..." }
}
}
}Tools are read-only and named comtrade_<verb>_<noun>. Results are capped at
200 rows or 64 KB with a note on how to narrow the query; comtrade_list_reporters and
comtrade_list_partners have a cap of their own, 400 rows or 100 KB, so their whole
tables reach the agent. comtrade_list_commodities has the same cap, but a
classification is larger (8,262 HS codes), so its note says to search. All three take
search: {"search": "switz"} returns 757 Switzerland. comtrade_get_world_share has the
same cap too, so one period for every reporter (214 rows for 2023) reaches the agent
whole; its note says to narrow by reporter_code or period. --http serves streamable
HTTP instead of stdio.
Status
Upstream operation | Task function | MCP tool | Status |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha; experimental upstream |
|
|
| alpha; experimental upstream |
|
|
| alpha; experimental upstream |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
All nineteen are covered in 0.2.0: twelve came with 0.1.0, the first release, and
get_trade_balance, get_bilateral_data, get_mirror_flows, get_comtrade_releases,
get_world_share, list_codes and list_classifications were released in 0.2.0. Alpha:
the public surface may change in a minor version before 1.0; CHANGELOG.md lists every
change.
Upstream terms and attribution
Data comes from UN Comtrade (https://comtradeplus.un.org), on the terms upstream states
for it in its Policy on Comtrade Data Use,
under which use of the data is subject to the license agreement at
https://comtrade.un.org/licenseagreement.html; this package adds no rights to it.
Documentation snapshot and its attribution: docs/upstream/FETCHED.md.
Licence
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
Comtrade MCP — UN Comtrade API for international bilateral trade data
Trade Intel MCP — Compound tools that chain Comtrade, Census, Treasury,
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides access to UN Comtrade international bilateral trade data via an MCP server, enabling AI agents to query trade statistics through natural language.85 npmMIT
- AlicenseNot gradedqualityBmaintenanceAccess UN Comtrade international merchandise and services trade statistics via MCP tools for country lookups, HS commodity search, bilateral trade flows, balances, rankings, and data availability.661 npm4Apache 2.0
- AlicenseAqualityBmaintenanceEnables querying Brazilian foreign trade data through MCP tools for trade flows, freight costs, code resolution, and dataset caveats, with known data defects corrected in responses.4MIT
- FlicenseNot gradedqualityBmaintenanceEnables secure, read-only querying of only predefined logical database views through MCP tools and a REST API, using validated SQL and semantic view metadata.-