grandline-mcp 0.1.0

MCP server for Grandline — empirical maritime distances + port lookups for LLM agents.

grandline-mcp

MCP server that gives Claude / Cursor / any MCP-capable LLM access to the Grandline maritime distance API — empirical sea distances derived from real AIS vessel tracks, four route variants (primary / via-Suez / via-Panama / via-Cape), 43M cached port-pair distances.

Install

pip install grandline-mcp

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "grandline": {
      "command": "grandline-mcp",
      "env": {
        "GRANDLINE_API_KEY": "gl_live_…"   // from grandline.luzomi.com/signup; omit for anonymous tier
      }
    }
  }
}

Restart Claude Desktop. Ask: "What's the empirical sea distance from Sabine Pass to Yokohama via Panama?" — Claude will call the right tools.

Tools exposed

Tool	What it does
port_lookup	Resolve a port name, UN-LOCODE, or lat/lon string into a canonical port record.
nearest_ports	Return the N nearest cataloged ports to a lat/lon coordinate.
find_route	Empirical sea distance between two ports for one of four route variants.
compare_routes	All four variants side-by-side with canal transits and steaming days.

Configuration

Env var	Default	Purpose
GRANDLINE_API_URL	https://grandline.luzomi.com/api/v1	Override the base URL (e.g. for self-hosted).
GRANDLINE_API_KEY	(unset)	Bearer token from signup; without it you're on the anonymous tier (10/day, 100/month per IP).
GRANDLINE_LOG_LEVEL	WARNING	Verbosity. Logs go to stderr so they don't corrupt the stdio protocol stream.

Status

Alpha. The HTTP backend is stable; the MCP tool descriptions are still being tuned for LLM-friendliness.

License

MIT.