# io.github.cyanheads/un-comtrade-mcp-server (remote · un-comtrade.caseyjhand.com)

UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.

- Trust score: 86/100 (high trust)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-05

## Components

- remote · `un-comtrade.caseyjhand.com`: 86/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade.md), [page](https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade)
- npm · `@cyanheads/un-comtrade-mcp-server`: 39/100, [markdown](https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/cyanheads-un-comtrade-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/cyanheads-un-comtrade-mcp-server)

## Channel facts

- Endpoint: `https://un-comtrade.caseyjhand.com/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.3.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-05.

- **Endpoint Security**: 83/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - No authorisation is required to call this server. Nothing on it is marked destructive, but we can't show that an anonymous caller can only read: full credit needs the server to list at least one tool and every tool to be verifiably read-only. We use a best-effort check of tool names and descriptions to tell read-only tools from tools that change things, so some genuinely read-only tools may not get full credit. Names that start with a read verb (get, list, read, search and similar) and accurate readOnlyHint annotations help. Meet that to earn full credit, or require authorisation.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC is configured correctly; the domain's records validate against the full chain to the root.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 76/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3457 tokens (~246/item across 14 items; 9 tools + 5 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 77/100
  - Stability observed for 23 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 9 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 11 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the io.github.cyanheads/un-comtrade-mcp-server server?

io.github.cyanheads/un-comtrade-mcp-server is a hosted endpoint at https://un-comtrade.caseyjhand.com/mcp, so there is nothing to install locally. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add --transport http cyanheads-un-comtrade-mcp-server 'https://un-comtrade.caseyjhand.com/mcp'
```

### Cursor

```json
{
  "mcpServers": {
    "cyanheads-un-comtrade-mcp-server": {
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "cyanheads-un-comtrade-mcp-server": {
      "type": "http",
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
```

### Codex

```toml
[mcp_servers.cyanheads-un-comtrade-mcp-server]
url = "https://un-comtrade.caseyjhand.com/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-un-comtrade-mcp-server": {
      "type": "remote",
      "url": "https://un-comtrade.caseyjhand.com/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-un-comtrade-mcp-server --url 'https://un-comtrade.caseyjhand.com/mcp' --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  cyanheads-un-comtrade-mcp-server:
    url: "https://un-comtrade.caseyjhand.com/mcp"
```

### Netclaw

```json
{
  "McpServers": {
    "cyanheads-un-comtrade-mcp-server": {
      "Transport": "http",
      "Url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
```

### Vellum

```bash
assistant mcp add cyanheads-un-comtrade-mcp-server -t streamable-http -u 'https://un-comtrade.caseyjhand.com/mcp'
```

### Other

```json
{
  "mcpServers": {
    "cyanheads-un-comtrade-mcp-server": {
      "type": "http",
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-05 (score 86, +1)

- [security] The server rewrote its instructions, which are the text every model session reads
- [security] Tool “comtrade_get_trade_balance” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_top_partners” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_services_trade” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_list_service_categories” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_lookup_countries” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_search_commodities” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_trade_flows” rewrote its description, which is the text the model reads
- [functional regression] Schema quality: 197 → 246
- [functional] Server version: 0.3.0 → 0.3.1
- [cosmetic] “comtrade_get_top_partners” added an optional parameter “classification”
- [cosmetic] “comtrade_get_services_trade” added an optional parameter “classification”
- [cosmetic] “comtrade_list_service_categories” added an optional parameter “offset”
- [cosmetic] “comtrade_search_commodities” added an optional parameter “offset”
- [cosmetic] “comtrade_get_trade_balance” reworded the description of “freq”
- [cosmetic] “comtrade_get_top_partners” reworded the description of “limit”
- [cosmetic] “comtrade_get_top_partners” reworded the description of “cmd_code”
- [cosmetic] “comtrade_get_top_commodities” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_top_commodities” reworded the description of “partner_code”
- [cosmetic] “comtrade_get_top_commodities” reworded the description of “limit”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “service_code”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “period”
- [cosmetic] “comtrade_get_data_availability” reworded the description of “freq”
- [cosmetic] “comtrade_get_trade_balance” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_trade_balance” reworded the description of “period”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “period”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “reporter_code”
- [cosmetic] “comtrade_list_service_categories” reworded the description of “limit”
- [cosmetic] “comtrade_list_service_categories” reworded the description of “parent_code”
- [cosmetic] “comtrade_search_commodities” reworded the description of “classification”
- [cosmetic] “comtrade_search_commodities” reworded the description of “limit”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “freq”

### 2026-11-03 (score 85, 0)

- [security] The server rewrote its instructions, which are the text every model session reads
- [security] Tool “comtrade_search_commodities” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_list_service_categories” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_top_commodities” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_services_trade” rewrote its description, which is the text the model reads
- [security] Tool “comtrade_get_data_availability” rewrote its description, which is the text the model reads
- [functional] New resource “un-comtrade-guide”
- [functional] Server version: 0.2.0 → 0.3.0
- [cosmetic] “comtrade_get_trade_balance” added an optional parameter “partner_code”
- [cosmetic] “comtrade_get_data_availability” added an optional parameter “offset”
- [cosmetic] “comtrade_get_data_availability” added an optional parameter “limit”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “flow_code”
- [cosmetic] “comtrade_search_commodities” reworded the description of “query”
- [cosmetic] “comtrade_search_commodities” reworded the description of “classification”
- [cosmetic] “comtrade_search_commodities” reworded the description of “aggr_level”
- [cosmetic] “comtrade_list_service_categories” reworded the description of “query”
- [cosmetic] “comtrade_list_service_categories” reworded the description of “parent_code”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “freq”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “cmd_code”
- [cosmetic] “comtrade_get_trade_flows” reworded the description of “classification”
- [cosmetic] “comtrade_get_trade_balance” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_trade_balance” reworded the description of “freq”
- [cosmetic] “comtrade_get_top_partners” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_top_partners” reworded the description of “period”
- [cosmetic] “comtrade_get_top_commodities” reworded the description of “period”
- [cosmetic] “comtrade_get_top_commodities” reworded the description of “partner_code”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “service_code”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “reporter_code”
- [cosmetic] “comtrade_get_services_trade” reworded the description of “period”
- [cosmetic] “comtrade_get_data_availability” reworded the description of “freq”
- [cosmetic] “comtrade_get_trade_flows” made “reporter_code” optional
- [cosmetic] Tool “comtrade_search_commodities” changed its title: Search HS Commodity Codes → Search Commodity Codes
- [cosmetic] Tool “comtrade_list_service_categories” changed its title: List Service Trade Categories (EBOPS) → List Service Trade Categories (EB)

### 2026-11-02 (score 85, +1)

No change was recorded against any check on this day. Stability & Change Management went from 63 to 67. That category is still filling its 30-day observation window: 19 days of observed history at the previous scan, 20 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-31 (score 84, +1)

No change was recorded against any check on this day. Stability & Change Management went from 57 to 60. That category is still filling its 30-day observation window: 17 days of observed history at the previous scan, 18 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-29 (score 83, +1)

No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-27 (score 82, +1)

No change was recorded against any check on this day. Stability & Change Management went from 43 to 47. That category is still filling its 30-day observation window: 13 days of observed history at the previous scan, 14 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-25 (score 81, +1)

No change was recorded against any check on this day. Stability & Change Management went from 37 to 40. That category is still filling its 30-day observation window: 11 days of observed history at the previous scan, 12 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-23 (score 80, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

## MCP tools (9)

### `comtrade_lookup_countries` (~306 tokens)

Lookup Countries / Areas

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, and validity dates; 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.

Input parameters:

- `include_groups` (boolean): Whether to include regional and economic groupings (e.g. EU, ASEAN). Set to false to return only individual countries.
- `query` (string, required): 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".
- `role` (string): 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.

Output parameters:

- `error` (object): Present when the call failed. Absent on success.
- `matches` (array): Matching entries, plus entries sharing an ISO-3 code with a match, ordered by exact ISO match, reporter validity, current before expired (entryExpiredDate before today), name, then code.
- `notice` (string): Recovery hint when no matches are found — echoes the query and suggests alternatives. Absent when results are non-empty.
- `totalMatches` (number): Total number of matching entries.

### `comtrade_search_commodities` (~302 tokens)

Search Commodity Codes

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), and 6 (subheading); SITC uses levels 1–5. Select the edition matching the trade records when interpreting historical codes. Each page holds up to limit matches; continue with nextOffset using the same query, classification, and aggr_level.

Input parameters:

- `aggr_level`: Native aggregation level: HS uses 2 (chapter), 4 (heading), 6 (subheading); SITC uses 1–5. Omit to return all matching levels.
- `classification` (string): 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 expli…
- `limit` (integer): Maximum matching codes returned per page; defaults to 50.
- `offset` (integer): Number of matching codes to skip; use nextOffset to continue.
- `query` (string, required): Keyword, partial description, or commodity code prefix. Examples: "motor vehicles", "8471", "coffee", "84" (HS chapter 84 = machinery).

Output parameters:

- `classification` (string): Reference catalog used for the search.
- `error` (object): Present when the call failed. Absent on success.
- `matches` (array): Commodity codes on this page matching the query in the selected classification, in catalog order.
- `nextOffset` (number): Offset for the next page; absent when no matching codes remain.
- `notice` (string): Recovery hint when no codes match, matches remain past this page, or the offset is past the end. Absent otherwise.
- `offset` (number): Number of matching codes skipped for this page.
- `shown` (number): Number of codes returned on this page.
- `totalMatches` (number): Total matching codes across all pages.
- `truncated` (boolean): Whether this page holds only part of the matching codes (shown < totalMatches).

### `comtrade_list_service_categories` (~289 tokens)

List Service Trade Categories (EB)

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). Filter by keyword (e.g. "transport", "financial", "travel") 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.

Input parameters:

- `limit` (integer): Maximum categories returned per page; defaults to 100.
- `offset` (integer): Number of matching categories to skip; use nextOffset to continue.
- `parent_code` (string): 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.
- `query` (string): Keyword or category code prefix to filter results. Examples: "transport", "SA", "financial services". Omit to list all EB categories.

Output parameters:

- `categories` (array): EB service categories on this page, in catalog order.
- `error` (object): Present when the call failed. Absent on success.
- `nextOffset` (number): Offset for the next page; absent when no matching categories remain.
- `notice` (string): Recovery hint when no categories match, matches remain past this page, the offset is past the end, or scheme tags are unavailable.
- `offset` (number): Number of matching categories skipped for this page.
- `shown` (number): Number of categories returned on this page.
- `totalMatches` (number): Total matching categories across all pages.
- `truncated` (boolean): Whether this page holds only part of the matching categories (shown < totalMatches).

### `comtrade_get_trade_flows` (~544 tokens)

Get Trade Flow Records

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

Input parameters:

- `classification` (string): Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.
- `cmd_code` (array): 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 for…
- `flow_code` (string, required): Trade flow direction: M=imports, X=exports, RX=re-exports, RM=re-imports.
- `freq` (string): Frequency: A=annual YYYY, M=monthly YYYYMM (01–12). Omit to infer it from the periods; an explicit value must match them.
- `partner_code` (integer): 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, required): 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 au…
- `reporter_code`: 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 report…

Output parameters:

- `error` (object): Present when the call failed. Absent on success.
- `notice` (string): Why data is missing: periods that were rate limited (with the wait) or ran out of time, and a recovery hint when no records are returned, naming the reporter-valid counterpart of a partner-only repor…
- `records` (array): Trade flow records.
- `referenceNotice` (string): Notice when reference descriptions could not be loaded; codes and trade values remain available.
- `reportersWithoutRecords` (array): Served codes from a reporter_code array with no records in any served period. Omitted when truncated, since a capped response can hide a reporter’s rows.
- `shown` (number): Number of records returned in this response.
- `totalCount` (number): Sum of upstream response counts before local filtering; not a full match count when capped.
- `truncated` (boolean): True when any preview response reached 500 and may be incomplete.
- `truncationHint` (string): Query narrowing and authenticated access guidance when possibly incomplete.
- `unservedCmdCodes` (array): Commodity codes beyond the 20-code work cap; query them separately.
- `unservedPeriods` (array): Periods not served: past the period cap (8 keyless, 12 authenticated) or whose requests were rate limited or ran out of time; query them separately.
- `unservedReporters` (array): Reporter codes beyond the 20-reporter work cap; query them separately.

### `comtrade_get_trade_balance` (~397 tokens)

Get Trade Balance

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 signed balance (USD), export value, import value, 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.

Input parameters:

- `classification` (string): Goods classification: HS/H0–H6 or SITC S1–S4/SS.
- `cmd_code` (array): 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.
- `freq` (string): 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_code` (integer): M49 partner code (0–999); defaults to World (0). The balance uses the reporter’s values.
- `period` (array, required): 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 r…
- `reporter_code` (integer, required): 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 exists…

Output parameters:

- `cmdCodes` (array): Commodity codes used in the query (absent when querying all commodities).
- `error` (object): Present when the call failed. Absent on success.
- `mirrorCaveat` (string): Standard caveat about mirror asymmetry — balance reflects this country's reported values.
- `notice` (string): Periods left out because a flow was rate limited (with the wait) or ran out of time, and possible incompleteness when a preview response reaches its cap.
- `partnerCode` (number): M49 partner code used.
- `partnerDesc` (string): Partner name supplied by the returned records, or its numeric code when unavailable.
- `periods` (array): Balance computation per period.
- `referenceNotice` (string): Reference descriptions unavailable; codes and trade values retained.
- `reporterCode` (number): M49 reporter code used.
- `reporterDesc` (string): Reporter country name.
- `unservedCmdCodes` (array): Commodity codes beyond the 20-code work cap; query them separately.
- `unservedPeriods` (array): Periods not served: past the period cap (4 keyless, 12 authenticated) or whose export or import request was rate limited or ran out of time; query them separately.

### `comtrade_get_top_partners` (~273 tokens)

Get Top Trading Partners

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.

Input parameters:

- `classification` (string): Goods classification: HS as reported, H0–H6 with authenticated access, or SITC S1–S4/SS.
- `cmd_code` (string): 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, required): Trade flow: M=imports, X=exports.
- `limit` (integer): Number of top partners to return; totalPartners counts every partner retrieved.
- `period` (string, required): Single period: annual YYYY or monthly YYYYMM, month 01–12; frequency is inferred.
- `reporter_code` (integer, required): M49 numeric code of the reporting country (0–999).

Output parameters:

- `classification` (string): Goods classification the commodity code was read in.
- `cmdCode` (string): Commodity code queried (TOTAL when omitted).
- `error` (object): Present when the call failed. Absent on success.
- `flowCode` (string): Flow direction queried.
- `notice` (string): Recovery hint when no data is returned.
- `partners` (array): Top partners sorted by descending trade value.
- `period` (string): Period queried.
- `referenceNotice` (string): Reference descriptions unavailable; codes and values retained.
- `reporterCode` (number): M49 reporter code.
- `reporterDesc` (string): Reporter country name.
- `totalPartners` (number): Partners retrieved before the limit, excluding the World (0) aggregate.
- `totalValueUsd` (number): Sum of primary values across all returned partners (before limit truncation).
- `truncated` (boolean): True when API returned 500 records and results may be incomplete.

### `comtrade_get_top_commodities` (~245 tokens)

Get Top Trade Commodities

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

Input parameters:

- `aggr_level`: HS aggregation level: 2 = chapter (broader), 4 = heading (more specific).
- `flow_code` (string, required): Trade flow: M=imports, X=exports.
- `limit` (integer): Number of top commodity categories to return; totalCommodities counts every category retrieved.
- `partner_code` (integer): M49 partner code (0–999) for a bilateral relationship; omit for World aggregate (0).
- `period` (string, required): Single period: annual (YYYY) or monthly (YYYYMM, month 01–12).
- `reporter_code` (integer, required): M49 numeric code of the reporting country (0–999).

Output parameters:

- `aggrLevel` (number): HS aggregation level used.
- `classificationCode` (string): HS edition identified by matching TOTAL.
- `commodities` (array): Top commodity categories sorted by descending trade value.
- `coverageComplete` (boolean): Whether every code in the matching HS edition was queried without a capped response.
- `coverageNotice` (string): Explanation of coverage and ranking availability.
- `denominatorValueUsd` (number): Matching TOTAL value used as the share denominator, separate from the retrieved-category sum.
- `error` (object): Present when the call failed. Absent on success.
- `flowCode` (string): Flow direction queried.
- `missingCodes` (array): Codes whose retrieval failed, remained capped, or did not fit the call's time budget; empty when the code universe is unavailable.
- `notice` (string): Recovery hint when no data is returned.
- `period` (string): Period queried.
- `reporterCode` (number): M49 reporter code.
- `reporterDesc` (string): Reporter country name.
- `totalCommodities` (number): Total commodity categories returned by API.
- `totalValueUsd` (number): Sum of primary values across all returned categories (before limit).
- `truncated` (boolean): True when complete commodity-code coverage could not be established.

### `comtrade_get_data_availability` (~297 tokens)

Check Data Availability

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 typically published 3–12 months after the reference year and not all countries report every year. Omit filters to browse the availability index, 50 rows by default. Continue with nextOffset using the same filters and limit.

Input parameters:

- `classification` (string): Classification code filter (e.g. "HS", "H6", "EB10"). Omitted or blank defaults to HS for goods and EB10 for services.
- `freq` (string): 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.
- `limit` (integer): Maximum datasets returned per page; defaults to 50.
- `offset` (integer): Number of matching datasets to skip; use nextOffset to continue.
- `period` (string): Period to check: YYYY (annual) or YYYYMM (monthly). Omit to see all available periods for the reporter.
- `reporter_code` (integer): M49 reporter code to check. Omit to browse availability across all reporters.
- `type_code` (string): Trade type: C=commodities (goods), S=services.

Output parameters:

- `datasets` (array): Available datasets matching the query.
- `error` (object): Present when the call failed. Absent on success.
- `nextOffset` (number): Offset for the next page; absent when no rows remain.
- `notice` (string): Recovery hint when no availability records are found.
- `offset` (number): Number of matching datasets skipped for this page.
- `shown` (number): Number of datasets returned on this page.
- `totalDatasets` (number): Total number of available dataset records.
- `truncated` (boolean): Whether this page contains only part of the matching dataset list.

### `comtrade_get_services_trade` (~477 tokens)

Get Services Trade Data

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

Input parameters:

- `classification` (string): 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…
- `flow_code` (string, required): Trade flow: M=imports (debits), X=exports (credits).
- `partner_code` (integer): M49 partner code. Use 0 for all partners combined. Omit for a disaggregated by-partner breakdown.
- `period` (array, required): 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 ceilin…
- `reporter_code` (integer, required): M49 numeric code of the reporting country (0–999).
- `service_code` (string): 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…

Output parameters:

- `error` (object): Present when the call failed. Absent on success.
- `notice` (string): Why data is missing: periods that were rate limited (with the wait) or ran out of time, and, when no records are returned, the requested code's EB scheme or a partner-only reporter's counterpart, wit…
- `records` (array): Services trade flow records.
- `referenceNotice` (string): Reference descriptions unavailable; codes and values retained.
- `shown` (number): Number of records returned.
- `totalCount` (number): Sum of upstream response counts before local filtering; not a full match count when capped.
- `truncated` (boolean): True when any preview response reached 500 and may be incomplete.
- `truncationHint` (string): Query narrowing and authenticated access guidance when possibly incomplete.
- `unservedPeriods` (array): Periods not served: past the period cap (8 keyless, 12 authenticated) or whose requests were rate limited or ran out of time; query them separately.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade#diagnostics

## Score history

- 2026-11-05: 86
- 2026-11-04: 85
- 2026-11-03: 85
- 2026-11-02: 85
- 2026-11-01: 84
- 2026-10-31: 84
- 2026-10-30: 83
- 2026-10-29: 83
- 2026-10-28: 82
- 2026-10-27: 82
- 2026-10-26: 81
- 2026-10-25: 81
- 2026-10-24: 80
- 2026-10-23: 80
- 2026-10-22: 79
- 2026-10-21: 79
- 2026-10-20: 78
- 2026-10-19: 78
- 2026-10-18: 78
- 2026-10-17: 77
- 2026-10-16: 77
- 2026-10-15: 76
- 2026-10-14: 76
- 2026-10-13: 75

## Common questions

### What is the io.github.cyanheads/un-comtrade-mcp-server server?

io.github.cyanheads/un-comtrade-mcp-server is listed in the public MCP registry as io.github.cyanheads/un-comtrade-mcp-server. UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings. This page covers its hosted endpoint (https://un-comtrade.caseyjhand.com/mcp).

### Is the io.github.cyanheads/un-comtrade-mcp-server server safe to use?

io.github.cyanheads/un-comtrade-mcp-server scores 86 out of 100 on VerifyMCP. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the io.github.cyanheads/un-comtrade-mcp-server server expose?

io.github.cyanheads/un-comtrade-mcp-server exposes 9 tools: comtrade_lookup_countries, comtrade_search_commodities, comtrade_list_service_categories, comtrade_get_trade_flows, comtrade_get_trade_balance, and 4 more. Their descriptions and schemas cost roughly 3,130 tokens of context every time the server is loaded.

### Does the io.github.cyanheads/un-comtrade-mcp-server server require authentication?

No. We connected to io.github.cyanheads/un-comtrade-mcp-server without credentials and it answered, so anything it exposes is reachable by anyone who knows the address.

### Is the io.github.cyanheads/un-comtrade-mcp-server server still maintained?

io.github.cyanheads/un-comtrade-mcp-server is still listed as active in the MCP registry. We last reached this channel on 5 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What did VerifyMCP test on the io.github.cyanheads/un-comtrade-mcp-server server?

VerifyMCP ran 13 checks on io.github.cyanheads/un-comtrade-mcp-server, covering TLS certificate, Authorization, HTTPS, HSTS header and 9 more. Supply Chain Security and Provenance & Transparency do not apply to a hosted endpoint, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- Remote endpoint: https://un-comtrade.caseyjhand.com/mcp
- Repository: https://github.com/cyanheads/un-comtrade-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-un-comtrade-mcp-server/un-comtrade