io.github.SaltyTaro/arcnautical
Screen any vessel by IMO for sanctions, ownership opacity and vetting grade. Keyless check included.
Open source Open in the app JSON README (API)
About
Screen any vessel by IMO for sanctions, ownership opacity and vetting grade. Keyless check included.
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- saltytaro
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-09-12T16:09:40Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-12 17:06:17
- Updated
- 2026-09-12 17:06:17
- Origin id
io.github.SaltyTaro/arcnautical
README
# @arcnautical/mcp
An [MCP](https://modelcontextprotocol.io) server for the [ArcNautical API](https://arcnautical.com/developers/): screen any commercial vessel by IMO number for sanctions, ownership opacity and a vetting grade — from Claude, ChatGPT, Cursor, VS Code, Windsurf or any MCP client.
**Two tools need no API key at all.** Install it, ask "is IMO 9274446 sanctioned?", get the answer.
```
IMO 9274446 HS STAR: sanctions RED — 4 confirmed matches on vessel identifier.
Ownership opacity MEDIUM. Vetting grade E (unacceptable). Checked 2026-09-12T08:10:40Z.
```
## Install
Requires Node 18+. No install step — every client below runs it with `npx`.
**Claude Desktop** — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"arcnautical": {
"command": "npx",
"args": ["-y", "@arcnautical/mcp"]
}
}
}
```
**Claude Code**
```
claude mcp add arcnautical -- npx -y @arcnautical/mcp
```
**Cursor / Windsurf / VS Code** — same `command` / `args` shape in the client's MCP settings.
To unlock the full record, batches and voyage scoring, add an API key to the `env` block:
```json
{
"mcpServers": {
"arcnautical": {
"command": "npx",
"args": ["-y", "@arcnautical/mcp"],
"env": { "ARCNAUTICAL_API_KEY": "arc_live_…" }
}
}
}
```
Keys are self-serve at https://arcnautical.com/arcnautical.html#/developer-api — no approval step. A key includes 5,000 vessel screenings and 10,000 voyage assessments a month.
## Tools
| Tool | Key? | What it does |
|---|---|---|
| `check_vessel` | no | Sanctions status (OFAC SDN, EU, UN, UK OFSI, OpenSanctions), ownership-opacity score, A–E vetting grade for one IMO. 100/hour per IP. |
| `find_port` | no | Resolve a port name or country to UN/LOCODEs — call before `score_voyage`. |
| `screen_vessel` | yes | The full screening record: every match with its source list, programme and confidence class, the graded vetting factors, per-source freshness, a retained record id. Same hull asked again today replays free. |
| `screen_vessels` | yes | Batch up to 50 IMOs and wait for the results. |
| `get_screening` | yes | Retrieve a stored record by id (retained ten years). |
| `score_voyage` | yes | Route risk between two LOCODEs: score, level, drivers, confidence, missing sources. |
| `get_usage` | yes | Remaining allowance and limits for the configured key. |
### Reading a verdict
- **RED** — confirmed match on the vessel identifier. **AMBER** — possible match, review it. **GREEN** — no match against the sources reached. **INCOMPLETE** — a core source could not be read; never present it as clear.
- `coverage_complete: false` on a GREEN means one supplementary list was unavailable: re-screen before relying on it.
- `assessed: false` means ownership and vetting are defaults, not findings.
- The keyless check matches the vessel's **current** name and identifiers only. A hull renamed after a designation can read GREEN there; `screen_vessel` covers that case.
- Designations change daily. Quote the `checkedAt` / `screened_at` time with any answer.
## Idempotency
Every resource-creating call sends an `Idempotency-Key` derived from the *question* — the hull and the UTC day — not from the attempt. Asking about the same vessel twice in a day returns the stored record and spends nothing. The API's docs measured 42% of one integration's monthly screenings as same-day repeats billed only because their client generated a random key per call; this server does not do that.
## Environment
| Variable | Default | Purpose |
|---|---|---|
| `ARCNAUTICAL_API_KEY` | unset | Enables the keyed tools. |
| `ARCNAUTICAL_BASE_URL` | `https://arcnautical.com` | Override for testing. |
## Links
- Guide: https://arcnautical.com/developers/
- Reference: https://arcnautical.com/developers/reference/
- OpenAPI 3.1: https://arcnautical.com/api/v1/openapi.json
- Postman: https://www.postman.com/arcnautical-6322764/arcnautical-s-workspace/collection/u7ua5ow/arcnautical-api-v1
- For agents: https://arcnautical.com/llms.txt
## Development
```
npm install
npm test # builds, then drives dist/cli.js over stdio against the live keyless endpoints
```
MIT © ArcNautical