trimtab-ais

# Trimtab AIS

**Machine-readable ship & port truth for AI agents.** Who is at berth, who is at anchor, at which
terminal, since when — at eight US container gateways, from AIS recorded continuously by this
project. Free, no key, no signup. Every response carries its method, its provenance, and its
limits, so your agent can verify instead of trust.

```
https://ais.trimtabist.com/mcp
```

## 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 |

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 instrument no. 001 in
a series measuring what trade data actually says versus what actually happens.