Skip to main content
Glama
htsapi.dev MCP server

htsapi.dev MCP server

README.md
# htsapi.dev MCP server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-8A2BE2)](https://modelcontextprotocol.io)
[![No key required](https://img.shields.io/badge/auth-none%20(keyless)-brightgreen)](https://htsapi.dev/developer-guide)

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](https://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)

## 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](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=htsapi.dev&connectorUrl=https%3A%2F%2Fhtsapi.dev%2Fmcp) opens the custom-connector dialog filled in. By hand: Settings, Connectors, Add custom connector, URL `https://htsapi.dev/mcp`.

**Claude Code**

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

**Cursor, Windsurf, Cline and other clients**

```json
{
  "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+.

```json
{
  "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](https://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](https://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](https://htsapi.dev/corpus).

## Also

- REST API over the same data: [htsapi.dev/docs](https://htsapi.dev/docs)
- For agents: [htsapi.dev/llms.txt](https://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.

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