grandline-mcp 0.2.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.
compare_route_matrix	Bulk M×N grid — every origin × every destination in one call (fleet / rate-card scale).

Example: bulk matrix

"Build a distance matrix from our load ports [11910, 13557] to discharge ports [9511, 12434]."

Claude calls compare_route_matrix(origins=[11910, 13557], destinations=[9511, 12434]) and gets all four cells back at once — each with distance_nm, the variant used, and an availability flag (available / estimated / route_not_in_cache). A 12×30 matrix is one call instead of 360 round-trips.

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 (5 calls total per IP).
GRANDLINE_LOG_LEVEL	WARNING	Verbosity. Logs go to stderr so they don't corrupt the stdio protocol stream.

Status

Beta (v0.2.0). The HTTP backend is stable and five tools are exposed. Tool descriptions are tuned for LLM-friendliness; compare_route_matrix is the newest addition.

License

MIT.