htsapi.dev MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@htsapi.dev MCP server What HTS code fits a stainless steel vacuum bottle from China?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
htsapi.dev MCP server
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_fileprompt)
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/mcpCursor, 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 |
| 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. |
| A code's section and chapter notes, or, without a code, the General Rules of Interpretation. |
| What CBP's rulings quote and decide on a heading. Give the product to get what decides for it first. |
| CBP rulings for a product described in plain words, with status and the codes they point to. |
| Every ruling under a code, and the rulings CBP revoked off it with where the goods went. |
| One ruling: full text, codes, status, what revoked or modified it, and what it cites. |
| What importers from a country paid on a code in the latest 3 Census months: history, not the duty owed. |
| 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
REST API over the same data: htsapi.dev/docs
For agents: htsapi.dev/llms.txt
Contact: hello@htsapi.dev
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 toolsclassify_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_notesARead-onlyIdempotentInspect
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_rulingARead-onlyIdempotentInspect
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_scopeARead-onlyIdempotentInspect
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_paidARead-onlyIdempotentInspect
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_codeARead-onlyIdempotentInspect
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_codeARead-onlyIdempotentInspect
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_rulingsBRead-onlyIdempotentInspect
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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Search USITC tariff schedules, inspect heading trees, and look up published duty rates.
Classify, validate & verify HS codes and access tariff compliance data for cross-border trade
Find US import tariff codes and duty rates from the current Harmonized Tariff Schedule.
US HTS search, origin-specific duty breakdowns, tariff sources and missing-fact guidance.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides access to US import tariff rates via the USITC Harmonized Tariff Schedule, enabling natural language queries for tariff data.82 npmMIT
- AlicenseBqualityBmaintenanceTurns 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.5342 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1Apache 2.0