trade-mcp-server

An MCP (Model Context Protocol) server that exposes U.S. trade data tools to AI agents — HTS product classification, tariff schedule search, and CBP ruling lookups. Listed on Smithery for agent discovery.

What it does

Connects any MCP-compatible AI agent to an HTS API so it can:

• Classify products into HTS codes using GRI reasoning
• Search the Harmonized Tariff Schedule by keyword or code prefix
• Search CBP binding rulings for legal precedents on specific goods

Requirements

• Node.js 18+
• A valid HTS API key (HTS_API_KEY)

Installation

Via npx (no install required)

npx @joshnunnery/trade-mcp-server

Via Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "trade": {
      "command": "npx",
      "args": ["@joshnunnery/trade-mcp-server"],
      "env": {
        "HTS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HTS_API_KEY | Yes | — | Your HTS API key | | HTS_API_URL | No | https://api.hts.trade | Base URL of the HTS API |

Available tools

classify_product

Classify a product into HTS codes. Returns ranked classifications with General Rules of Interpretation (GRI) reasoning.

Inputs:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | description | string | Yes | Plain-language product description | | country_of_origin | string | No | ISO 3166-1 alpha-2 country code (e.g. CN, DE) |

Example prompt: "Classify cotton knit t-shirts from Bangladesh"

search_hts

Search the Harmonized Tariff Schedule by keyword or code prefix. Returns matching HTS codes and descriptions.

Inputs:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Product name, keyword, or HTS code prefix |

Example prompt: "Find HTS codes for lithium-ion batteries"

search_rulings

Search U.S. Customs and Border Protection (CBP) binding rulings. Returns relevant ruling citations for a product or legal issue.

Inputs:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Product name, ruling number, or legal question |

Example prompt: "Find CBP rulings on the country of origin for assembled electronics"

optimize_tariff

Analyze tariff optimization opportunities for a product across four vectors: material composition, country of origin, first sale valuation, and FTA qualification.

Inputs:

| Parameter | Type | Required | Description | |-----------|------|----------|--------------| | product_description | string | Yes | Plain-language product description | | chapter | number | Yes | HTS chapter number (e.g. 64 for footwear) | | material_composition | object | Yes | Map of material name to percentage, e.g. {"leather": 60, "synthetic": 40} | | country_of_origin | string | Yes | ISO 3166-1 alpha-2 country code (e.g. VN, CN) | | annual_import_value | number | Yes | Annual import value in USD | | current_hts | string | No | Current HTS classification, if known |

Example prompt: "What are my tariff optimization options for a leather sneaker upper (60% leather, 40% synthetic) imported from Vietnam at $500k/year?"

Note: This tool can take 45-90 seconds to complete. If your MCP client enforces a default request timeout (many default to ~60s), configure a longer timeout (120s recommended) for this tool specifically, or calls may be cut off before the analysis finishes even though the server is still processing correctly.

Local development

git clone https://github.com/joshnunnery/trade-mcp-server.git
cd trade-mcp-server
npm install
cp .env.example .env   # fill in HTS_API_KEY
npm run build
npm start

License

MIT