`comtrade_trade_data`

Pack: comtrade · Endpoint: https://gateway.pipeworx.io/comtrade/mcp

No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/comtrade_trade_data for the schema, then POST the same URL with its arguments for the data.

Trade values and quantities between two countries, from UN Comtrade customs statistics.

Tool description as the model sees it

AUTHORITATIVE bilateral trade data between two countries from UN Comtrade — the official international-trade statistics database (every country’s customs filings, harmonized). Returns trade values USD, quantities, and HS commodity-level detail for imports and exports between reporter + partner. Use for “how much X did US import from China in 2024”, “what does Germany export to Brazil”, “Mexico’s top trade partners by commodity”, or “how did Saudi–Egypt trade move this year” (pass frequency=“monthly” for month-by-month, not just last year’s annual total). UN Comtrade reporter/partner codes (842=US — Comtrade uses 842, NOT the ISO 840; 156=China, 276=Germany, 0=World — see comtrade_country_codes). Defaults to ANNUAL data (lags ~3 months from reporting period); pass frequency=“monthly” for month-level data (lags more and some reporters never file monthly — a missing month is simply absent from the result, never shown as a zero). Every response states its own “frequency” so a monthly figure is never mistaken for an annual one.

Parameters

Name	Type	Required	Description
`reporter_code`	string	yes	Country name (e.g. “USA”, “China”, “Germany”) or UN numeric code (US=842, China=156). Names are resolved automatically.
`partner_code`	string	yes	Partner country name (e.g. “China”) or UN code (156=China, 0=World). Optional — defaults to World (0). Names resolved automatically.
`year`	string	yes	Trade period. For frequency=“annual” (default): a year, e.g. “2024”. For frequency=“monthly”: year+month as YYYYMM, e.g. “202401” for January 2024.
`hs_code`	string	no	HS commodity code at 2/4/6 digit level (e.g., “8471” for computers). Optional — omit for all commodities.
`flow`	string	no	Trade flow: “M” for imports, “X” for exports. Optional — defaults to both “M,X”.
`frequency`	string	no	Data frequency: “annual” (default) for yearly totals, or “monthly” for month-level data. Monthly coverage is thinner than annual — not every reporter files monthly, and recent months lag by reporter; a country-month with no filing is simply omitted from the results, not returned as zero. When “monthly”, pass `year` as YYYYMM.

Example call

Arguments

{
  "reporter_code": "842",
  "partner_code": "156",
  "year": "2024"
}

curl

curl -X POST https://gateway.pipeworx.io/comtrade/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"comtrade_trade_data","arguments":{"reporter_code":"842","partner_code":"156","year":"2024"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('comtrade_trade_data', {
  "reporter_code": "842",
  "partner_code": "156",
  "year": "2024"
});

More examples

{
  "reporter_code": "842",
  "partner_code": "156",
  "year": "2023",
  "hs_code": "8471",
  "flow": "M"
}

{
  "reporter_code": "682",
  "partner_code": "818",
  "year": "202401",
  "frequency": "monthly"
}

Response shape

Field	Type	Description
`count`	number	Number of trade records returned
`year`	string	Trade year queried
`records`	array

Full JSON Schema

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of trade records returned"
    },
    "year": {
      "type": "string",
      "description": "Trade year queried"
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reporter": {
            "type": "string",
            "description": "Reporting country name"
          },
          "partner": {
            "type": "string",
            "description": "Partner country name"
          },
          "flow": {
            "type": "string",
            "description": "Trade flow type (Imports, Exports, Re-exports, Re-imports)"
          },
          "commodity_code": {
            "type": "string",
            "description": "HS commodity code"
          },
          "commodity": {
            "type": "string",
            "description": "Commodity description or code"
          },
          "trade_value_usd": {
            "type": "number",
            "description": "Trade value in USD"
          },
          "net_weight_kg": {
            "type": [
              "number",
              "null"
            ],
            "description": "Net weight in kilograms"
          },
          "quantity": {
            "type": [
              "number",
              "null"
            ],
            "description": "Trade quantity"
          },
          "quantity_unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unit of quantity measurement"
          }
        }
      }
    }
  }
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "comtrade": {
      "url": "https://gateway.pipeworx.io/comtrade/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

comtrade_trade_data