trackline-mcp

A zero-dependency Python MCP client that bridges Claude Code (and other MCP hosts) to the Trackline railway data platform over Streamable HTTP. Distributed as a uvx-runnable package — no manual installation or virtualenv required.

Installation

Via uvx (recommended)

No installation needed. Run directly:

uvx trackline-mcp --auth

Via pip

pip install trackline-mcp
trackline-mcp --auth

Authentication

Trackline MCP uses OAuth 2.0 Device Authorization Grant (no browser redirect required). You authenticate once and the token is cached at ~/.trackline/token.json with automatic refresh via an offline token.

Step 1 — Authenticate in a terminal:

uvx trackline-mcp --auth

This opens a URL. Visit it, log in, and the token is cached automatically.

Step 2 — Connect from Claude Code (see config below — no manual step needed).

Claude Code / MCP Configuration

Add to your .mcp.json (project or global):

{
  "mcpServers": {
    "trackline": {
      "command": "uvx",
      "args": ["trackline-mcp"]
    }
  }
}

How It Works

1. On first run (--auth), the client performs a Device Authorization Grant with Keycloak, opening a short URL for you to approve.
2. The token (including an offline refresh token) is cached at ~/.trackline/token.json.
3. On subsequent runs, the client reads the cached token and refreshes it automatically if needed.
4. JSON-RPC messages from Claude Code arrive on stdin and each is POSTed independently to the Trackline MCP server (/mcp); the JSON response is forwarded to stdout. Concurrent tool calls run in parallel — the server is stateless streamable-HTTP, so each request is fully independent.