Skip to main content
Glama
htsapi.dev MCP server

htsapi.dev MCP server

htsapi.dev MCP server

License: MIT MCP No key required

Give your AI agent what a customs classifier reads when it picks a US tariff code:

  • the Harmonized Tariff Schedule (USITC) one level at a time, with its section and chapter notes and the General Rules of Interpretation;

  • over 222,000 CBP rulings (CROSS) in full text, each with its status: revoked or modified, by which ruling, and where the goods went;

  • what CBP's rulings quote and decide on a heading: the Explanatory Note passages and legal notes CBP relied on, grouped across rulings, with what each ruling concluded;

  • what importers paid on a code from a country in the latest 3 months of US Census data.

Your agent classifies; the importer decides. Everything is guidance from public sources, not legal advice or a binding ruling. Why sources rather than a code from us: htsapi.dev/method.

What you can ask

  • "What HTS code fits a stainless steel vacuum bottle made in China, and what did importers actually pay on it?"

  • "Has CBP ruled on silicone baking mats? Are those rulings still in force?"

  • "What do CBP's rulings say separates heading 9021 from 6406 for shoe insoles?"

  • "Read ruling N046655 and tell me whether anything revoked or modified it."

  • "Write a classification file for a battery-powered milk frother from Vietnam." (the classification_file prompt)

Related MCP server: tariff-resolver

Connect

The hosted server is https://htsapi.dev/mcp (Streamable HTTP). The read tools need no key and no signup.

Claude (claude.ai, desktop, mobile): Add to Claude opens the custom-connector dialog filled in. By hand: Settings, Connectors, Add custom connector, URL https://htsapi.dev/mcp.

Claude Code

claude mcp add --transport http htsapi https://htsapi.dev/mcp

Cursor, Windsurf, Cline and other clients

{
  "mcpServers": {
    "htsapi": { "url": "https://htsapi.dev/mcp" }
  }
}

With a key, add "headers": { "X-API-Key": "YOUR_KEY" } next to "url" (or --header "X-API-Key: YOUR_KEY" in Claude Code).

Clients that only run local servers

This repository is a stdio server that forwards to the hosted one. It has no data or logic of its own, so its tools are always the hosted server's. Requires Node 18+.

{
  "mcpServers": {
    "htsapi": {
      "command": "npx",
      "args": ["-y", "github:rozetyp/htsapi-mcp"],
      "env": { "HTSAPI_KEY": "optional, only for classify_product" }
    }
  }
}

Tools

Tool

Returns

lookup_hts_code

The schedule one level at a time: sections and chapters, a chapter's headings, a heading's subheadings, a line's rates and the rulings under it.

get_notes

A code's section and chapter notes, or, without a code, the General Rules of Interpretation.

heading_scope

What CBP's rulings quote and decide on a heading. Give the product to get what decides for it first.

search_rulings

CBP rulings for a product described in plain words, with status and the codes they point to.

rulings_under_code

Every ruling under a code, and the rulings CBP revoked off it with where the goods went.

get_ruling

One ruling: full text, codes, status, what revoked or modified it, and what it cites.

importers_paid

What importers from a country paid on a code in the latest 3 Census months: history, not the duty owed.

classify_product

Our own classifier's suggestion, a second opinion. Needs a key; 1 credit.

Prompt classification_file: the method and the eight sections of a broker's classification file. The server's instructions walk an agent through the method: facts, GRI 1 with the notes, GRIs 2 to 6, a check against rulings and their status, then the report.

How well it works, measured on 54 CBP cases with each case's own ruling hidden: htsapi.dev/classification-accuracy.

Limits and price

  • No key: the seven read tools, 50 calls a day per IP, 10 a minute.

  • Prices, and what a key adds: htsapi.dev.

Not covered

The duty owed on a shipment, anti-dumping and countervailing duties, other agencies' rules, court opinions, and the full text of the WCO Explanatory Notes (only the passages CBP quotes in its rulings). Counts, freshness and what is missing: htsapi.dev/corpus.

Also

License

MIT for this repository. The data comes from USITC, US Customs and Border Protection and the US Census Bureau; htsapi.dev is independent and not affiliated with them.

Available Tools

8 tools
classify_productAInspect

Classify a product to a US HTS code. COSTS 1 CREDIT (refunded if it fails). Takes 10-60 s.

Read `answer` first. `answer.code` is as deep as the facts given decide (10 digits when they
do). When they do not, `answer.options` are the codes it could be, each with its `condition`,
base rate and `importers_paid`, and `answer.question` is the fact that decides: ask the user,
then call again with the answer added to the description (a new call, 1 credit).
`candidates` carry the reasoning and the CBP rulings behind each code.

Inputs: description (required), material, country_of_origin. Returns: object

get_notesA
Read-onlyIdempotent
Inspect

The legal text that decides between headings, from the official US schedule. With a code: its section's notes and its chapter's notes, subheading notes, Additional U.S. Notes and statistical notes. These have legal force (GRI 1): they exclude goods from a chapter ("this chapter does not cover...") and define terms. Without a code: the General Rules of Interpretation and the Additional U.S. Rules of Interpretation. The WCO Explanatory Notes are not included (copyrighted); heading_scope gives the passages CBP rulings quote from them.

Inputs: code. Returns: object

get_rulingA
Read-onlyIdempotent
Inspect

One CBP ruling: its full text, HTS codes, status and, when revoked or modified, the ruling that did it, the codes it moved the goods to, and the sentence that says so. Codes the current schedule no longer has are listed in obsolete_codes. cites: the explanatory notes, legal notes and GRIs it relies on (heading_scope shows what rulings say a heading covers).

Inputs: ruling_number (required). Returns: object

heading_scopeA
Read-onlyIdempotent
Inspect

What CBP's rulings quote and decide on a heading: for deciding whether a product falls in it. Give the product to get what decides for it first. passages: the lines rulings quote when deciding (mostly from the WCO Explanatory Notes, not published free; fragments, not the whole note), each with the rulings that quote it: their goods, HQ or NY, date, status and what CBP concluded; exclusion marks text on what the heading does not cover. notes_applied: the legal notes rulings applied to the heading. cited_without_quote: rulings that relied on its explanatory note without quoting it. Each passage is as a ruling quotes it.

Inputs: heading (required), product. Returns: object

importers_paidA
Read-onlyIdempotent
Inspect

What importers from a country actually paid on a code in the latest 3 months Census has published: base rate plus Chapter 99 duties (Section 301, 232 and the like), as a percent of value, by month. Not the duty a shipment will owe today (Census is about 2 months behind and the rules change), and anti-dumping/countervailing duties are not included. For "what will this cost", not for classifying.

Inputs: code (required), country_of_origin (required). Returns: object

lookup_hts_codeA
Read-onlyIdempotent
Inspect

The tariff schedule, one level at a time, the way a classifier reads it. No code: the 22 sections and their chapters, for goods no ruling covers. A chapter (82) lists its headings with their legal text; a heading (8205) lists its subheadings in words; a subheading or line gives its path from the heading (an "Other" line says what it is not), base rates with the special-rate programs named, the 10-digit lines under it and the newest current CBP rulings under it. A code no longer in the schedule falls back to the nearest level that is. What importers paid is a separate tool, importers_paid.

Inputs: code. Returns: object

rulings_under_codeA
Read-onlyIdempotent
Inspect

Every CBP ruling that classifies goods under a code: for checking a code someone already has. rulings are current (not revoked), newest first, or closest to product first, each with what its goods were; moved_away are rulings CBP revoked off this code and the codes the revoking ruling put the goods under. If similar goods were moved away, the code is in doubt.

Inputs: code (required), limit, offset, product. Returns: object

search_rulingsB
Read-onlyIdempotent
Inspect

CBP rulings for a product described in plain words, by meaning. Each ruling comes with its HTS codes, its status (current, modified, superseded) and the product facts CBP classified. by_code lists the subheadings current rulings point to, in the order of the rulings, each with its HQ rulings, newest ruling and lines: the full codes under it with the rulings for each, which is where the facts that decide between lines show.

Inputs: query (required), limit. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    The two retrieval entry points are clearly distinguished (search_rulings by product meaning vs rulings_under_code by code), and get_ruling is a distinct single-record fetch. classify_product, lookup_hts_code and importers_paid are explicitly contrasted in their descriptions. The only soft overlap is get_notes vs heading_scope, which both surface legal notes applied to a heading/code, though one is statutory text and the other ruling-quoted explanatory passages.

    Naming Consistency4/5

    All names use snake_case, which is consistent throughout. Most follow verb_noun (search_rulings, get_ruling, classify_product, lookup_hts_code, get_notes), with a few noun-phrase exceptions (importers_paid, heading_scope, rulings_under_code) that are still readable and self-descriptive.

    Tool Count5/5

    Eight tools is well within the ideal range and each maps to a distinct step in the classification workflow: search, retrieve, classify, browse the schedule, read notes, read explanatory scope, check historical rulings, check duty paid. No tool appears redundant or filler.

    Completeness4/5

    The surface covers the full classification research loop from product description to code lookup to legal authority to real-world duty evidence. Minor gaps: there is no forward duty calculator or special-program/TRQ eligibility check, and AD/CVD is explicitly out of scope and has no tool, but agents can work around these via importers_paid and lookup_hts_code.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides access to US import tariff rates via the USITC Harmonized Tariff Schedule, enabling natural language queries for tariff data.
      82 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Turns your AI assistant into a US import duty research tool, enabling HTS code lookup, landed-cost calculation, and tariff change tracking using official USITC data.
      5
      342 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search Chinese HS commodity codes, retrieve detailed tariff and regulatory information, and calculate import taxes using 2026 import/export tariff data.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching U.S. Harmonized Tariff Schedule commodity descriptions and code prefixes, inspecting classification headings and ancestry, browsing chapters, and retrieving published duty-rate columns and partial Chapter 99 evidence via MCP.
      86 npm
      1
      Apache 2.0