@chrtco/mcp

Model Context Protocol (MCP) server for the CHRT nautical chart API. It lets AI coding agents — Claude Desktop, Cursor, and any MCP client — run CHRT spatial queries over official ENC data mid-conversation, without writing throwaway fetch code.

A thin layer over @chrtco/sdk. Zero config beyond an API key.

⚠️ NOT FOR PRIMARY NAVIGATION. CHRT data is derived from official electronic navigational charts but is not for primary navigation and is not SOLAS-compliant. Always use official, type-approved ECDIS or paper charts for navigation safety. CHRT provides situational awareness data only. Every tool repeats this disclaimer in its description and in every response — agents must relay it to end users.

What it exposes

| Tool | What it does | Wraps | |---|---|---| | chrt_ahead | What's charted in a sector ahead of a position (bearing + arc + range), with distance, bearing and depth clearance per feature — plus a coverage block, because an empty result is not an all-clear | chrt.ahead | | chrt_along_route | What's charted in a corridor along a planned route, ordered by along_m — how far into the passage you meet each feature. Same invariants; an empty result is not a clear passage | chrt.alongRoute | | chrt_nearby | Charted features within a radius of a point | chrt.query | | chrt_features_bbox | Charted features inside a bounding box | chrt.features | | chrt_cell | One ENC cell's metadata + data currency (issue_date, update_number, edition), or list cells | chrt.cells.get / chrt.cells.list | | chrt_coverage | Where CHRT has coverage + issuing hydrographic offices | chrt.coverage.list |

Resources: chrt://coverage and chrt://cells (read-only JSON snapshots).

Every response surfaces the non-SOLAS disclaimer, the issuing hydrographic-office attribution, and data currency — these are non-negotiable invariants.

There is intentionally no tile-URL tool — this server exposes spatial queries only. (Tiles are a separate workstream.)

Prerequisites

• Node.js 18+ (npx ships with npm).
• A CHRT API key. Create a scoped, server-side key at https://chrt.co/platform/keys.

Quick start

The server is launched by your MCP client via npx — you usually don't run it by hand. It reads the API key from the CHRT_API_KEY environment variable.

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chrt": {
      "command": "npx",
      "args": ["-y", "@chrtco/mcp"],
      "env": {
        "CHRT_API_KEY": "chrt_sk_live_your_scoped_key"
      }
    }
  }
}

Restart Claude Desktop. You'll see the CHRT tools in the tool picker.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "chrt": {
      "command": "npx",
      "args": ["-y", "@chrtco/mcp"],
      "env": {
        "CHRT_API_KEY": "chrt_sk_live_your_scoped_key"
      }
    }
  }
}

Cursor → Settings → MCP shows the server and its tools once saved.

Any MCP client

Run the binary directly over stdio:

CHRT_API_KEY=chrt_live_... npx -y @chrtco/mcp

Configuration

| Env var | Required | Description | |---|---|---| | CHRT_API_KEY | ✅ | Your CHRT API key (chrt_sk_live_… / chrt_sk_test_…). | | CHRT_API_BASE_URL | | Override the API base URL (default https://api.chrt.co/v1). For staging / self-host. |

Handling your API key safely

• Use a dedicated, scoped key for the MCP server (restrict scopes / coverage / IP at https://chrt.co/platform/keys). Don't reuse a broad production key.
• Keep the key in the client config env block (as above) or your shell environment — never paste it into an agent prompt or transcript, and never commit it to source control.
• Server-side use only. Treat the key like a password.
• Rotate the key if it's ever exposed.

Example prompts

Once configured, ask your agent things like:

• "Use CHRT to find wrecks and obstructions within 2 km of 42.02 N, 70.86 W."
• "What wrecks and obstructions are in the bounding box around Boston Harbor?"
• "How current is ENC cell US5MA11M? Show me the issue date and update number."
• "Does CHRT have coverage for the US, and which office issues it?"

The agent will call the relevant tool and must relay the disclaimer, the issuing office, and the data currency in its answer.

Getting good results

• Name the feature classes you care about. chrt_nearby takes a layer filter ("WRECKS,OBSTRN,UWTROC", "LIGHTS", "BOYLAT", …). Without one it also returns the full outlines of the coarse-scale polygons that merely contain your point — those rank first, because a containing polygon is 0 m away — which can run to megabytes and exhaust an agent's context on a single question. Use limit to bound results further.
• chrt_cell filters take ids: source: "NOAA_ENC" (the chart-source id), status: "CURRENT". Call chrt_coverage for the valid source ids.
• No features ≠ safe water. Outside CHRT's coverage the tools return zero features. That means uncharted in CHRT — never that the water is clear.

Local development

This package lives in the CHRT monorepo and depends on @chrtco/sdk via the workspace.

bun install
bun run --filter @chrtco/sdk build   # REQUIRED FIRST — see below
cd packages/mcp
bun run build        # bundle the bin to dist/
bun run typecheck
bun run test         # vitest — handler unit tests + an in-memory protocol test

The SDK build is not optional. bun resolves @chrtco/sdk from the workspace (node_modules/@chrtco/sdk → packages/sdk), and the SDK's exports point only into its gitignored dist/. On a fresh checkout, typecheck, test and build all fail to resolve the module until you build the SDK.

Live verification against the real API

The unit tests mock the SDK. src/live.test.ts drives the real thing and is skipped unless CHRT_API_KEY is set (so CI stays green and offline):

CHRT_API_BASE_URL=https://api-staging.chrt.co/v1 \
CHRT_API_KEY=<staging fixture key> \
bun run --cwd packages/mcp vitest run live

Mint a disposable 24 h staging key per .claude/context/staging-plan-fixtures.md. Findings from the last full run: docs/validation/mcp-live-verification-2026-07.md.

To run the built server by hand:

CHRT_API_KEY=chrt_sk_test_... node dist/index.js

All diagnostics go to stderr — stdout is reserved for the MCP protocol stream.

License

MIT