io.github.mrsingh86/trimtab-ais
US tariff & trade truth: duty actually paid by origin/HS 2017+, HTS rulebook, CBP rulings. No key.
Open source Repository Open in the app JSON README (API)
About
US tariff & trade truth: duty actually paid by origin/HS 2017+, HTS rulebook, CBP rulings. No key.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mrsingh86
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.3.0
- Last push
- 2026-08-11T16:36:26Z
- Repository state
- ativo
- Language
- JavaScript
- License
- Apache-2.0
- Added
- 2026-08-29 04:00:51
- Updated
- 2026-08-29 04:00:51
- Origin id
io.github.mrsingh86/trimtab-ais
README
# Trimtab US Trade Ledger — MCP server for US tariff & trade data
**What US importers actually paid at the border — free, no API key, no signup.**
Official duty receipts by product and origin, monthly since 2017, reconciled monthly against the
US Treasury's own customs receipts (both books: assessed at entry and kept after refunds — May and
June 2026 ran negative). Plus the current HTS rulebook with Federal Register citations, CBP
classification rulings, HS code search, US containerised imports by origin × commodity × gateway
(revision-tracked), and a frozen 2026 archive of own-recorded AIS ship movements. Every response
carries its method, its provenance, and its limits, so your agent can verify instead of trust.
Published by **[Trimtabist](https://trimtabist.com)** — the independent observatory for US trade.
20 pre-registered ruled studies (nulls published), a public corrections log, and the whole
collection pipeline open at [trimtab-pipeline](https://github.com/mrsingh86/trimtab-pipeline).
**Endpoint (streamable HTTP, no auth):**
```
https://trimtabist.com/mcp
```
Official MCP registry: `com.trimtabist/us-tariff-ledger` · 13 tools + an archive router ·
docs for agents: [trimtabist.com/llms.txt](https://trimtabist.com/llms.txt) ·
connect guides: [trimtabist.com/connect](https://trimtabist.com/connect)
## Why
Carrier tracking data doesn't mean what it says. The same event label can mean "alongside the dock"
for one carrier and "waiting at anchor" for another — a difference of hours to days, which is
exactly the difference that decides a demurrage clock, a drayage appointment, or a customer
promise. Meanwhile the carriers have been closing their doors to automated readers: several now
block AI crawlers *by name* in `robots.txt`, and not one of the top ten runs a public developer
portal.
So the software now making shipping decisions is arguing from paperwork it cannot check. This
instrument offers the other half: **physics**. A ship is either moving or it isn't; it is either
alongside a container terminal or it isn't. AIS says so, we record it continuously, and we publish
what we see — including what we can't.
## Add it to your agent
Claude Code:
```bash
claude mcp add --transport http trimtab-ais https://ais.trimtabist.com/mcp
```
Claude Desktop or any MCP client (HTTP transport):
```json
{ "mcpServers": { "trimtab-ais": { "url": "https://ais.trimtabist.com/mcp" } } }
```
Clients that require stdio:
```json
{ "mcpServers": { "trimtab-ais": { "command": "npx", "args": ["-y", "trimtab-ais"] } } }
```
## Use it from code
```bash
npm i trimtab-ais
```
```js
import { gatewayConditions, vesselStatus, hasVesselBerthed } from 'trimtab-ais';
const la = await gatewayConditions('us_la_longbeach');
// → { gateways: [{ at_berth: { by_class: { container: 8, tanker: 3, ... } },
// at_anchor: { ... }, container_terminals: { "LA Pier 400 (APM)": [...] } }],
// as_of, method, coverage, source, attribution }
await vesselStatus('MSC DARLENE');
// → moored, container, 366 m, LA Terminal Island (Fenix/Everport), since 2026-07-26T14:47Z
await hasVesselBerthed('EVER MEGA', 72);
// → { berthed: true, events: [{ at, gateway, terminal, queue_wait_min }] }
```
Or from the shell, with no install:
```bash
npx trimtab-ais gateway us_savannah
npx trimtab-ais vessel "ONE ORPHEUS"
npx trimtab-ais berthed "MSC DARLENE" 48
```
Or straight over HTTPS — it is plain JSON-RPC:
```bash
curl -X POST https://ais.trimtabist.com/mcp -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"gateway_conditions","arguments":{"gateway":"us_ny_nj"}}}'
```
## The tools
| Tool | Answers |
|---|---|
| `gateway_conditions` | What's happening at a gateway now — vessels at berth and at anchor, classified (container / bulk-general / tanker / service), with container terminals named |
| `vessel_status` | Where a vessel is, what it's physically doing, which terminal, since when, declared destination |
| `has_vessel_berthed` | Whether a vessel berthed within a lookback window — timestamp, terminal, anchorage wait if it queued |
| `recent_events` | The event stream: arrivals, anchorings, berthings, departures, and semantic notes |
US Trade Ledger series tools (Census-recorded port trade + cross-checks):
| Tool | Answers |
|---|---|
| `list_instruments` | Every instrument and data series, with provenance grade and trust state — start here |
| `describe_series` | What one series measures: unit, source, method, citation, coverage |
| `query_series` | The data: monthly US port trade by country & commodity, vessel events, ETA reliability |
| `check_agreement` | Census customs records vs live AIS observation — where independent instruments disagree, one is wrong |
| `search_series` | Find series by plain language: "imports from india", "houston", "vessel arrivals" |
Gateways: `us_la_longbeach` `us_ny_nj` `us_savannah` `us_houston` `us_charleston` `us_norfolk`
`us_oakland` `us_seattle_tacoma`
## What it covers — and what it doesn't
An instrument that hides its blind spots isn't an instrument.
- **Covered:** the eight US container gateways above.
- **Recorded but thin:** Chennai/Ennore/Kattupalli; JNPT, Mundra, Pipavav, Hazira, Vizhinjam,
Colombo — terrestrial receivers are sparse there, so coverage is partial to absent. Published, not
papered over.
- **Not covered:** mid-ocean (terrestrial AIS only, no satellite), cargo (AIS sees ships, never
boxes), rates, schedules, or anything a carrier declares rather than does.
- **Archive begins 26 July 2026,** with one disclosed gap (2026-07-26 17:20Z → 2026-07-27 12:16Z)
from the instrument's first day. Durations that began before recording started are lower bounds,
and say so.
**[Read the method →](https://ais.trimtabist.com/method)** — sources, state-machine thresholds,
how container ships are distinguished from bulkers (AIS type codes can't), known limits, and the
correction policy. Written so a stranger can reproduce the numbers, or prove them wrong.
## Licence and citation
Data **CC BY 4.0**, code **Apache 2.0**. Use it commercially, build on it, redistribute it — with
attribution:
> Trimtab AIS (ais.trimtabist.com), built by Mrigank Singh
Not for regulatory or safety-of-life reliance; no warranty. If you find it wrong,
[tell me](mailto:mrigank@intoglo.com) — corrections are published, with the size of the error
quantified.
---
Built and maintained by **[Mrigank Singh](https://mriganksingh.ai)**, who moves containers for a
living — co-founder & COO of Intoglo, an India→US freight forwarder. This is the live-observation layer of the
Trimtab US Trade Ledger, which measures what trade data actually says versus what actually happens.