io.github.cyanheadsPublished by GitHub account cyanheadsv0.1.2Updated Oct 26, 2026
Search USITC tariff schedules, inspect heading trees, and look up published duty rates.
Searches the U.S. Harmonized Tariff Schedule from USITC, letting an assistant look up commodity descriptions, heading trees and published duty rate columns.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Fusitc-tariffs-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"usitc-tariffs": {
"type": "http",
"url": "https://usitc-tariffs.caseyjhand.com/mcp"
}
}
}Search USITC tariff schedules, inspect heading trees, and look up published duty rates via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://usitc-tariffs.caseyjhand.com/mcp
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.
usitc_search_hts toolquery: commodity text or a code prefix. limit defaults to 25, with at most 100 items per page; follow page.nextCursor with the same arguments.context: "flat_search_matches" and rows with ratesResolved: false. Use heading lookup for ancestry and duty lookup for resolved base columns; no matches is a successful empty result.usitc_get_heading toolcode: four, six, or eight digits, bare or conventionally dotted. Optional returned nodeId selects an exact node; limit defaults to 25, at most 100 per page.nodes with parentId, executable parentFollowUp, and resolvedRates states of published, inherited, or not_published. Unnumbered superior rows remain part of the hierarchy; published subchapter titles are preserved separately in sections. A missing classification returns found: false.usitc_browse_chapter toolchapter: 01–99, accepting one or two digits. limit defaults to 25, at most 100 entries per page.rateLineCount and statisticalLineCount per 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 toolcode; optional ISO alpha-2 countryCode. 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.found: false. Blank statistical cells inherit only from the matching eight-digit legal ancestor; blank never means zero or Free.specialPrograms preserves unmatched text and parseCoverage; Special-program membership remains unknown, and eligibility and column selection remain not_determined. With countryCode, countryAssessment.column2Listing reports membership in the reviewed General Note 3(b) list for its pinned edition, or unknown when editions differ. Country input does not select a rate or establish preference qualification.usitc_check_additional_duties toolcode, excluding Chapter 99; optional countryCode. view is candidates (default), evidence (requires returned candidateCode), or unmapped. limit defaults to 25, at most 100 per page.coverage.status is always partial; inspect supportedGrammar, limitations, and unresolved evidence. Candidate legalStatus is not_determined. Unknown and different-country evidence remains visible; an empty candidate list never establishes clearance.nextCall and evidence followUp objects. For passages, supply noteId and optional noteCursor with the original code/country selectors, omitting view, candidateCode, and collection cursor; concatenate all notesPage.fragments across pages and inspect governing context.usitc_list_reference tooltopic: identifiers, spi, chapters, units, or releases. limit defaults to 25, at most 100 entries per page.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:
Agent-friendly output:
release, source, and notices; edition checks prevent detected cross-edition mixing, but do not prove atomic publication or current law.total, returned, effectiveLimit, and nextCursor; a 24,000-byte complete-reply budget can reduce page size with budgetLimited: true. Cursors bind the original arguments and source snapshot, expire within 15 minutes, and can expire earlier after eviction or restart.found, rate states, partial coverage, and typed error reasons support branching without guessing. Restart the original call without cursors after cursor_expired; fix selectors after invalid_cursor or invalid_selector.content[] and structuredContent carry the same selected data; published source text is framed as data rather than instructions.Connect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
No API key is required. For Docker or a source build, see Running the server.
No server-specific environment variables are required. See .env.example for common framework overrides.
Requires Bun v1.4.0 or higher (or Node.js v24+ for the published package) and network access to hts.usitc.gov.
No 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:
Run checks and tests:
The 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.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for logging and pass ctx.signal through to upstream workcreateApp() array in src/index.tsIssues are welcome. Run checks and tests before submitting:
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Source: README.md at commit 56344de
Search published HTS classifications
Search published USITC descriptions or complete HTS code prefixes in source order. Matches are flat published rows with unresolved rates; call usitc_get_heading for legal ancestry and usitc_lookup_duty_rate for exact base rate columns. Follow nextCursor with identical arguments for all remaining matches.
limitqueryrequiredcursorInspect an HTS heading and ancestry
Inspect a four-, six- or eight-digit HTS classification and its complete indented descendants, including unnamed superior rows. Published section titles are retained separately in sections, outside legal ancestry. Ancestry is built from the whole containing heading before filtering. Each parent and inherited-rate source has an exact nodeId follow-up. Chapters 98 and 99 preserve published forest roots without inventing four-digit records.
coderequiredlimitcursornodeIdBrowse published HTS chapter headings
Browse numbered headings with complete distinct eight-digit rate-line relationships and independent ten-digit statistical counts. A unique combined ten-digit source row can establish an absent eight-digit relationship. Published subchapter titles group following headings when present. Chapters 98 and 99 expose actual published entries without synthetic four-digit headings; grouping is unavailable without sourced markers. Reserved chapters can return a successful empty collection.
limitcursorchapterrequiredLook up published base duty columns
Retrieve an eight-digit rate line or exact ten-digit statistical number with all published General, Special and Column 2 cells. An explicit eight-digit row takes precedence; an absent one resolves only through a unique ten-digit source row, retaining its identity. Multiple suffixes stay unresolved. Blank statistical cells inherit only from the matching eight-digit legal ancestor. With countryCode, report edition-matched General Note 3(b) listing; Special-program membership stays unknown. Neither comparison establishes qualification or selects a column. Follow usitc_check_additional_duties for partial Chapter 99 research.
coderequiredcountryCodeResearch Chapter 99 additional-duty evidence
Find Chapter 99 candidate headings and source references for an exact eight- or ten-digit commodity number. Coverage is partial and empty candidates never establish clearance. Use candidates, evidence with a returned candidateCode, or unmapped views; follow returned noteId and noteCursor for complete source passages. Country comparisons retain unknown and different-country evidence. No applicability, current legal status, exclusions, stacking or combined duties are determined.
coderequiredviewlimitcursornoteIdnoteCursorcountryCodecandidateCodeDecode HTS references and published editions
List accepted identifier formats, edition-pinned Special Program Indicators, chapter/section navigation labels, quantity units or published release metadata. Program names are decoded separately from country membership, which remains unknown without independently verified lists. Release records identify published editions but do not enable historical tariff lookup. Follow nextCursor for all entries.
limittopicrequiredcursor100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add --transport http usitc-tariffs-mcp-server https://usitc-tariffs.caseyjhand.com/mcpclaude mcp add usitc-tariffs-mcp-server -- npx -y @cyanheads/usitc-tariffs-mcp-server{ "mcpServers": { "usitc-tariffs-mcp-server": { "command": "npx", "args": ["-y", "@cyanheads/usitc-tariffs-mcp-server"] } }}git clone https://github.com/cyanheads/usitc-tariffs-mcp-server.gitcd usitc-tariffs-mcp-serverbun installcp .env.example .env# One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdiobun run devcheck # Lints, formats, type-checks, and morebun run test # Runs the test suitedocker run --rm -p 3010:3010 ghcr.io/cyanheads/usitc-tariffs-mcp-server:latestbun run devcheckbun run test