uscensus-intl-trade-api-mcp

An MCP (Model Context Protocol) server for the U.S. Census Bureau's International Trade Data API — monthly U.S. export and import statistics, January 2010–present, by Harmonized System (HS), NAICS, End-Use, SITC, USDA (Ag/Non-Ag), and Advanced Technology classifications, plus state- and port-level detail.

Setup

1. Get a free Census API key: https://api.census.gov/data/key_signup.html (you'll get an email with an activation link — click it before using the key).

2. Install dependencies and build:

   npm install
   npm run build

3. Set your API key:

   cp .env.example .env
   # edit .env and set CENSUS_API_KEY

4. Add to your MCP client (e.g. Claude Desktop / Claude Code config):

   {
     "mcpServers": {
       "census-trade": {
         "command": "node",
         "args": ["/absolute/path/to/uscensus-intl-trade-api-mcp/dist/index.js"],
         "env": { "CENSUS_API_KEY": "your_40_character_key_here" }
       }
     }
   }

By default the server runs over stdio. Set TRANSPORT=http (and optionally PORT) to run it as a local streamable-HTTP server instead (binds to 127.0.0.1 only).

Related MCP server: Census MCP Server

Tools

Testing

• node scripts/smoke-test.mjs — starts the server, lists tools, and exercises the two tools that don't require a live Census API call. No real API key needed.

• CENSUS_API_KEY=<real key> node scripts/live-test.mjs — exercises real Census API calls end-to-end (needs a real key and outbound network access to api.census.gov).

Evaluations

evaluation/questions.xml has 10 verified Q&A pairs for testing how well an LLM can use this server, built on the mcp-builder evaluation harness (evaluation/evaluation.py). All questions use January/June 2013 data — final, long-settled figures chosen so the answers never change.

pip install -r evaluation/requirements.txt
export ANTHROPIC_API_KEY=your_api_key
python evaluation/evaluation.py \
  -t stdio -c node -a dist/index.js \
  -e CENSUS_API_KEY=<your census key> \
  -o evaluation/report.md \
  evaluation/questions.xml

Notes on the underlying API

• Filtering by country uses a numeric CTY_CODE (Schedule C), not the country name — use census_trade_lookup_country_code to translate.

• Descriptive text fields (CTY_NAME, DIST_NAME, *_LDESC, etc.) require their matching code field also be requested, or the API errors.

• Don't mix commodity-classification parameters across datasets (e.g. don't filter by NAICS on the hs dataset).

• Large, unfiltered queries (e.g. all countries × all 10-digit HS codes) commonly time out — narrow with filters or split wildcard queries (E_COMMODITY=1*, then 2*, etc.) and combine client-side.

• A response with zero rows isn't necessarily an error — it can just mean no trade occurred for that filter combination.

• Quantity fields (QTY_1_MO, QTY_2_MO, GEN_QY1_MO, GEN_QY2_MO, CON_QY1_MO, CON_QY2_MO, and their *_YR variants) report "0" for both true zeros and missing/unavailable data — always request the matching *_FLAG field (e.g. QTY_1_MO_FLAG) alongside a quantity field; "M" means missing, blank means a true zero.

• Requesting CTY_CODE without summary_level="DET" returns individual countries and regional/bloc groupings (e.g. 4XXX Europe, 0001 OPEC) mixed in the same response — summing across all rows double-counts. Set summary_level="DET" before aggregating across countries yourself.

Full reference: Census International Trade Data API User Guide (PDF).