comtrade-mcp-server 0.1.0

MCP server for UN Comtrade API access

UN Comtrade MCP Server

A Model Context Protocol (MCP) server that provides access to the UN Comtrade international trade statistics API. This server enables AI assistants like Claude to query and analyze global trade data directly.

Features

The Comtrade MCP server provides tools for:

• Trade Data Queries: Preview or retrieve detailed trade data (final and tariff line data)
• Data Availability: Check what data is available for specific criteria
• Metadata: Access publication notes and metadata about trade datasets
• Reference Data: Query reference tables (countries, commodities, trade flows, etc.)
• Country Code Conversion: Convert ISO3 country codes to Comtrade codes
• Live Updates: Get notifications about recent data releases

Installation

Using uvx (Recommended)

The easiest way to use this MCP server is with uvx:

uvx comtrade-mcp-server

Using pip

pip install comtradeapicall
cd mcp-server
pip install -e .

Configuration

For Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "comtrade": {
      "command": "uvx",
      "args": ["comtrade-mcp-server"],
      "env": {
        "COMTRADE_SUBSCRIPTION_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

• COMTRADE_SUBSCRIPTION_KEY (optional): Your UN Comtrade API subscription key
  • Required for: get_trade_data, get_live_updates
  • Not required for: preview_trade_data, get_data_availability, get_metadata, reference tools
  • Get a free key at: https://comtradeplus.un.org/

Available Tools

1. preview_trade_data

Preview final trade data (limited to 500 records). No subscription key required.

Example use: "Show me a preview of Australia's imports of commodity code 91 in May 2022"

Parameters:

• typeCode: "C" (Goods) or "S" (Services)
• freqCode: "A" (Annual) or "M" (Monthly)
• clCode: Classification code (e.g., "HS", "SITC")
• period: Time period (e.g., "2022" for annual, "202205" for monthly)
• reporterCode: Country code (use get_reference with "reporter" to find codes)
• cmdCode: Commodity code(s), comma-separated (e.g., "91" or "91,90")
• flowCode: Trade flow ("M" for imports, "X" for exports)
• partnerCode (optional): Partner country code
• breakdownMode (optional): "classic" or "plus"
• includeDesc (optional): Include descriptions (default: true)

2. get_trade_data

Get full trade data with subscription key (up to 250K records). Requires subscription key.

Example use: "Get detailed trade data for France's exports in 2022"

Parameters: Same as preview_trade_data plus:

• maxRecords (optional): Maximum records to return (default: 2500)

3. get_data_availability

Check what trade data is available. Free to use.

Example use: "What trade data is available for 2021?"

Parameters:

• typeCode: "C" or "S"
• freqCode: "A" or "M"
• clCode: Classification code
• period: Time period
• reporterCode (optional): Country code (omit for all countries)

4. get_metadata

Get metadata and publication notes. Free to use.

Example use: "Get metadata for monthly data in May 2022"

Parameters:

• typeCode: "C" or "S"
• freqCode: "A" or "M"
• clCode: Classification code
• period: Time period
• reporterCode (optional): Country code
• showHistory (optional): Show historical notes (default: false)

5. list_references

List all available reference tables. Free to use.

Example use: "What reference tables are available?"

Parameters:

• category (optional): Filter by category (e.g., "cmd:HS")

6. get_reference

Get contents of a specific reference table. Free to use.

Example use: "Get the list of reporter countries"

Common categories:

• reporter: Reporter countries
• partner: Partner countries
• flow: Trade flow codes
• customs: Customs procedure codes
• mot: Mode of transport codes

Parameters:

• category: Reference category name

7. convert_country_iso3_to_code

Convert ISO3 country codes to Comtrade codes. Free to use.

Example use: "Convert USA, FRA, and CHE to Comtrade codes"

Parameters:

• iso3_codes: Comma-separated ISO3 codes (e.g., "USA,FRA,CHE")

8. get_live_updates

Get recent data releases. Requires subscription key.

Example use: "What data was recently released?"

Usage Examples

With Claude Desktop

After configuration, you can ask Claude:

1. "What countries are available in Comtrade?"
2. "Show me Australia's imports of electronics in May 2022"
3. "Convert USA, GBR, and JPN to Comtrade country codes"
4. "What trade data is available for 2021?"
5. "Get metadata for monthly HS classification data in June 2022"

Programmatically

# The MCP server runs as a subprocess and communicates via stdio
# Typically used through MCP clients like Claude Desktop

Data Types and Codes

Type Codes

• C: Goods (Commodities)
• S: Services

Frequency Codes

• A: Annual
• M: Monthly

Classification Codes

Common classifications include:

• HS: Harmonized System
• SITC: Standard International Trade Classification
• Use list_references to see all available classifications

Flow Codes

• M: Imports
• X: Exports
• RE: Re-exports
• RM: Re-imports

Learn More

• UN Comtrade Documentation
• UN Comtrade Developer Portal
• Model Context Protocol
• comtradeapicall Python Package

License

MIT License - See LICENSE file for details

Support

For issues specific to this MCP server, please open an issue on GitHub.

For UN Comtrade API questions, visit the UN Comtrade Developer Portal.