usitc-tariffs-mcp-server
Public Hosted Server: https://usitc-tariffs.caseyjhand.com/mcp
Overview
The U.S. Harmonized Tariff Schedule from the USITC. Search commodity descriptions, inspect classification ancestry, read published base duty columns, and investigate partial Chapter 99 evidence. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above; no upstream account or API key is required.
Tools
Tool | Description |
| Search descriptions and code prefixes as flat published matches |
| Inspect classification ancestry, descendants, and inherited-rate sources |
| Browse chapter headings with rate-line and statistical-line counts |
| Retrieve every published base duty column for an exact rate or statistical line |
| Research Chapter 99 candidates, evidence, and complete supporting passages |
| Decode identifiers, program symbols, chapters, units, and edition metadata |
Related MCP server: mcp-trade-compliance
Capability reference
usitc_search_hts tool
Required
query: commodity text or a code prefix. OptionalcodePrefix(chapter61, or6109,6109.10,6109.10.00) keeps only matches under that code before counting and paging.limitdefaults to 25, with at most 100 items per page; followpage.nextCursorwith the same arguments.Returns
context: "flat_search_matches"and rows withratesResolved: false. Use heading lookup for ancestry and duty lookup for resolved base columns; no matches is a successful empty result.
usitc_get_heading tool
Required
code: four, six, eight, or ten digits, bare or conventionally dotted; a ten-digit code selects that statistical line and its indented descendants. Optional returnednodeIdselects an exact node;limitdefaults to 10, at most 100 per page.Returns flat source-order
nodeswithparentId, executableparentFollowUp, andresolvedRatesstates ofpublished,inherited, ornot_published. Published columns carry onlystateandtext; inherited columns also name their source row withsourceFollowUp. Unnumbered superior rows remain part of the hierarchy; published subchapter titles are preserved separately insections. A missing classification returnsfound: false.
usitc_browse_chapter tool
Required
chapter:01–99, accepting one or two digits.limitdefaults to 25, at most 100 entries per page.Returns complete
rateLineCountandstatisticalLineCountper published subtree, counting a unique combined row's eight-digit relationship once. Published subchapter markers group following headings. Chapters 98 and 99 retain their actual numbered entries; grouping stays absent without a verified marker, and reserved chapters can return an empty collection.
usitc_lookup_duty_rate tool
Required eight- or ten-digit
code; optional ISO alpha-2countryCode. Identifiers retain leading zeros and accept conventional dots. An absent eight-digit row resolves only through its unique published ten-digit row, preserving the source number; ambiguous suffixes remain unresolved. Ten-digit requests require their exact published number.Returns General, Special, and Column 2 cells in
row.resolvedRateswith rate-source provenance, orfound: false. Blank statistical cells inherit only from the matching eight-digit legal ancestor; blank never means zero orFree.specialProgramspreserves unmatched text andparseCoverage; Special-program membership remainsunknown, and eligibility and column selection remainnot_determined. WithcountryCode,countryAssessment.column2Listingreports membership in the reviewed General Note 3(b) list when the checked edition is the reviewed2026HTSRev21or one verified to carry identical General Note 3 text (editionMatches: true), andunknownotherwise; provenance stays on the reviewed edition. Country input does not select a rate or establish preference qualification.
usitc_check_additional_duties tool
Required exact eight- or ten-digit base commodity
code, excluding Chapter 99; optionalcountryCode.viewiscandidates(default),evidence(requires returnedcandidateCode), orunmapped.limitdefaults to 10 (includingnoteIdpages), at most 100 per page.coverage.statusis alwayspartial; the first candidates page carriessupportedGrammarand the coverage facts, parser limitations, including the clearance limit, are in every page'snotices, and unresolved evidence is in the unmapped view. CandidatelegalStatusisnot_determined. Unknown and different-country evidence remains visible; an empty candidate list never establishes clearance.Explicit “following” clauses can link directly owned numbered code lists to their governing heading, with separate passage follow-ups. Descriptive items remain qualified context. Reviewed single-country “product(s) of China” or “product(s) of Canada” scopes can label country relations; exceptions, conditions and conflicting scopes remain unknown.
Follow returned
nextCalland evidencefollowUpobjects. For passages, supplynoteIdand optionalnoteCursorwith the original code/country selectors, omittingview,candidateCode, and collectioncursor; concatenate allnotesPage.fragmentsacross pages and inspect governing context.
usitc_list_reference tool
Required
topic:identifiers,spi,chapters,units, orreleases.limitdefaults to 25, at most 100 entries per page.spiandunitspages state edition, citation, and source once indecoder. SPI country membership remains unknown; release records describe published editions without enabling historical tariff lookup.
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
USITC-specific:
Keyless access to the HTS application's undocumented interfaces, with paced requests and bounded retries.
Published descriptions, rate strings, units, sparse fields, and footnotes preserved alongside legal ancestry.
Edition-pinned Special Program Indicator decoding and partial Chapter 99 evidence research.
No conclusive classification, preference qualification, duty stacking, combined-duty calculation, or current-enforceability determination. Confirm legal applicability against legal notes and current CBP/Federal Register guidance.
Agent-friendly output:
Provenance — every result carries
release,source, andnotices; edition checks prevent detected cross-edition mixing, but do not prove atomic publication or current law.Complete continuation — pages expose
total,returned,effectiveLimit, andnextCursor; every page but the last returns exactlyeffectiveLimitwhole items (the requested limit, clamped to 100), and a clamped limit addsRequested limit <n> was clamped to the 100-item page cap.tonotice. Cursors bind the original arguments and source snapshot, expire within 15 minutes, and can expire earlier after eviction or restart.Explicit uncertainty —
found, rate states, partial coverage, and typed error reasons support branching without guessing. Restart the original call without cursors aftercursor_expired; fix selectors afterinvalid_cursororinvalid_selector.Matching response surfaces —
content[]andstructuredContentcarry the same selected data; published source text is framed as data rather than instructions.
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http usitc-tariffs-mcp-server https://usitc-tariffs.caseyjhand.com/mcpOr run it locally:
claude mcp add usitc-tariffs-mcp-server -- npx -y @cyanheads/usitc-tariffs-mcp-serverFor other clients, add this to the MCP config file:
{
"mcpServers": {
"usitc-tariffs-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/usitc-tariffs-mcp-server"]
}
}
}No API key is required. For Docker or a source build, see Running the server.
Configuration
Variable | Description | Default |
| Transport: |
|
| HTTP bind address. |
|
| HTTP server port. |
|
| MCP endpoint path. |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level ( |
|
| Directory for log files (Node.js only). |
|
| Storage backend: |
|
| Enable OpenTelemetry. |
|
No server-specific environment variables are required. See .env.example for common framework overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+ for the published package) and network access to hts.usitc.gov.
git clone https://github.com/cyanheads/usitc-tariffs-mcp-server.git
cd usitc-tariffs-mcp-server
bun install
cp .env.example .envNo server-specific variables are required; adjust framework overrides as needed. For Streamable HTTP, run MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http after building; the endpoint is http://localhost:3010/mcp.
Build and run the production version:
# One-time build bun run rebuild # Run the built server bun run start:http # or bun run start:stdioRun checks and tests:
bun run devcheck # Lints, formats, type-checks, and more bun run test # Runs the test suite
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/usitc-tariffs-mcp-server:latestThe image serves HTTP on port 3010 with stateless sessions and logs under /var/log/usitc-tariffs-mcp-server; configure authentication before exposing it publicly. For a stdio MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/usitc-tariffs-mcp-server:latest"]. To build locally, run docker build -t usitc-tariffs-mcp-server .; add --build-arg OTEL_ENABLED=false to omit optional telemetry peers.
Project structure
Directory | Purpose |
| Six definitions, shared output schemas, and lossless response formatting |
| Fixed-origin HTTP client, edition checks, pacing, and derived snapshots |
| Hierarchy, base-rate resolution, and argument-bound pagination |
| Identifier validation and edition-pinned reference decoders |
| Partial evidence indexing, selectors, and passage fragments |
| Agent skill shipped in the npm package, Docker image, MCPB bundle and plugins, and served over MCP |
| Tests and public-source fixtures mirroring |
|
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor logging and passctx.signalthrough to upstream workRegister new tools in the
createApp()array insrc/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Keep partial-coverage and country-qualification limits intact when extending the Chapter 99 evidence grammar
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Find US import tariff codes and duty rates from the current Harmonized Tariff Schedule.
HTS MCP — US import tariff rates via the USITC Harmonized Tariff Schedule.
US import tariff lookup against the official USITC 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
- AlicenseNot gradedqualityCmaintenanceEnables US import compliance by providing CBP customs ruling letter searches and antidumping/countervailing duty order lookups, answering how Customs has classified products and whether trade-remedy duties apply.80 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables looking up UK commodity codes and their full tariff details, including duty rates by origin, VAT, excise, import/export conditions, and live quota balances.291 npmMIT
- AlicenseNot gradedqualityBmaintenanceRead-only MCP tools for querying USDA FAS Global Agricultural Trade System census export and import records by partner country, year, month and HS10 code prefix, plus the release-date lists for each flow. Results are capped with notes on omitted rows, and responses carry release vintages and retrieval metadata.Apache 2.0