Tariff Resolver

What tariff-resolver MCP server does

The tariff-resolver MCP server provides local research tools for US import classification and duty estimation. It uses a bundled snapshot of official USITC Harmonized Tariff Schedule data containing more than 35,000 tariff lines. The server can identify likely HTS candidates from a product description, show associated rates, and include links to CBP CROSS rulings.

For a selected HTS code, origin, and customs value, it returns the base MFN or FTA rate, possible Chapter 99 additions, and separate MPF and HMF calculations. Weight can also be supplied for scenario calculations. Results identify the match and confidence for each candidate Chapter 99 layer and preserve source information for provisions that may have expired.

The tariff-resolver MCP server is intended for pre-broker screening, landed-cost comparison, and tariff research. It is not customs, legal, or tax advice, and its estimates do not include antidumping or countervailing duties.

How it works

The server runs against its local dataset rather than making network requests during normal use. Its MCP tools retrieve data and structure the result; the connected language model is responsible for interpreting the returned rules and exception chains. Chapter 99 text is supplied with parsed rates where applicable, allowing the model to inspect the source rule rather than rely on an opaque total.

Ten-digit statistical suffixes inherit rates from their parent tariff line. Schedule headings marked as terminated, suspended, or expired are filtered from the active layers and counted separately. A status override can place a matching provision in possibly_expired, along with its status, reason, source URL, and effective date. Results also include the dataset snapshot date and a stacking warning because published schedules may not reflect the latest collection status.

Origin accepts an ISO-3166 alpha-2 code or an English country name. An unrecognized country produces an ORIGIN_UNKNOWN error instead of silently calculating a thinner set of duties.

Setup and configuration

Node.js 18 or later is required. The package can be started through npx:

claude mcp add tariff-resolver -- npx -y tariff-resolver

Alternatively, add a stdio server entry to an MCP client configuration:

{
  "mcpServers": {
    "tariff-resolver": {
      "command": "npx",
      "args": ["-y", "tariff-resolver"]
    }
  }
}

Claude Desktop users can install the release .mcpb package by downloading it and opening it. The included dataset can be refreshed with python3 scripts/fetch_hts.py; this optional script retrieves data from the official USITC API and fails rather than writing an incomplete dataset. dataset_info reports the revision date, row count, source, and license.

Tools and capabilities

• search_hs_candidates maps a product description to likely HTS codes, rates, and CBP CROSS ruling links.
• calculate_tariff_scenario evaluates an HTS code, origin, value, and optional weight, returning base rates, candidate Chapter 99 layers, possible expired provisions, and MPF/HMF.
• watch_tariff_changes stores HTS codes in a local watchlist.
• check_tariff_updates compares the current data with the previous HTS revision and reports changed rates.
• dataset_info describes the local data snapshot.

The watchlist is stored in a local JSON file. No queries, telemetry, analytics, or runtime data are transmitted.

Limitations and notes

Tariff layers are candidates, not a guaranteed amount charged at entry. Collection status can change before the published schedule reflects it, so current CBP CSMS messages should be checked before relying on a duty stack. The bundled data is US government public-domain material, while the server is licensed under MIT.