MCP METRO

Moscow and Saint Petersburg metro for AI agents. Ask "how do I get from Khovrino to Sportivnaya?" in plain language — get real route variants with travel times, transfers, car-boarding hints and today's closures. Both networks answer through one tool. Understands Russian, English, Arabic and Chinese. Typos welcome.

What it does

• 🚇 Routes people can actually follow — up to 3 variants with travel time, every station on the way, transfer walks, a door-to-door estimate and "board the first car" hints for faster interchanges.

• 🏙 Two cities, one tool — 21 Moscow lines with MCC and MCD, 6 Saint Petersburg lines; one city argument switches datasets, and each city is loaded and refreshed independently.

• 🚧 Knows what's closed today — escalator repairs, closed stations, closed transfers and official detours are applied to the route graph before the search runs, not footnoted after.

• 🌍 Understands humans, not codes — typos, transliteration (hovrino) and Russian case forms (до Чеховской) all resolve; Moscow names are matched and returned in four languages, Petersburg names in Russian.

• 🖼 Interactive widget (MCP Apps) — SEP-1865 hosts get clickable route cards whose «from» / «to» selects recompute the trip in place; text-only hosts get clean Markdown, and nobody gets a wall of JSON.

• 🚈 Beyond the tunnel — vestibule hours and first/last trains in both cities; in Moscow also ground transport at either end and on-station services.

• ⚡ Never hostage to the network — every city has a backup source behind its primary one and an atomic disk cache, refreshed daily; the server answers within a second of starting.

• 🔌 Every way in — MCP over STDIO / HTTP / SSE, a rate-limited REST API with Swagger at /docs, and a built-in Agent Tester that drives the tool through a real LLM.

One tool — metro_info — answers the two questions a passenger asks: how do I get from A to B (search_route) and what is there at station X (get_station_info), in the city its city argument selects.

Related MCP server: tomsk-transport

Try it in 60 seconds

npm install
npm run build
npm start            # HTTP mode → http://localhost:9049

curl http://localhost:9049/health

MCP endpoint: http://localhost:9049/mcp. No database, no API keys, no credentials — it just runs. Client configs are one click away: Connect your client below.

Documentation

The tool, up close

One tool — metro_info, read-only. action=search_route builds up to 3 route variants between two stations; action=get_station_info describes one station. city picks the network — Moscow by default, Saint Petersburg on request. Answers are English Markdown; station and line names are localized to the user's language.

A search_route answer contains: up to 3 route variants with travel time and a door-to-door estimate, the full station sequence of every leg, transfers with "board the first car" hints, which legs run on MCD / MCC, ground transport at both ends, advisories along the route, and the vestibule status of the departure hub.

A get_station_info answer contains: lines at the station, city exits with nearby ground transport, on-station services, first and last train times per direction, available interchanges, and current advisories.

Saint Petersburg answers carry the same routes, transfers, hours and closures, but no ground transport, no on-station services and no train-car hints — its sources do not publish them; station names come in Russian.

When a name is ambiguous the answer is a numbered list to choose from; for a route request with two ambiguous names, both lists come at once.

Full reference, including MCP resources and prompts: Tool Reference. What each city carries: Cities.

Connect your client

{
  "mcpServers": {
    "mcp-metro": {
      "type": "http",
      "url": "http://localhost:9049/mcp",
      "headers": {
        "Authorization": "Bearer <jwt-token>"
      }
    }
  }
}

Omit the headers block entirely while authentication is off (the default).

Option 1 — STDIO (local build, direct spawn):

{
  "mcpServers": {
    "mcp-metro": {
      "command": "node",
      "args": ["<path-to-project>/dist/src/start.js", "stdio"],
      "env": {}
    }
  }
}

Option 2 — HTTP (remote server via mcp-remote):

{
  "mcpServers": {
    "mcp-metro": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp-metro.time-gold.com/mcp",
        "--header",
        "Authorization:Bearer <jwt-token>",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}

Important: in --header values there must be no space after the :. "Authorization:Bearer abc" is correct, "Authorization: Bearer abc" is not.

{
  "mcpServers": {
    "mcp-metro": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp-metro.time-gold.com/mcp",
        "--header",
        "Authorization:Bearer <jwt-token>",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}

The same no-space-after-: rule applies to --header values.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-metro": {
      "type": "remote",
      "url": "http://localhost:9049/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <jwt-token>"
      }
    }
  }
}

Omit the headers block entirely while authentication is off (the default).

[mcp_servers.mcp-metro]
url = "https://mcp-metro.time-gold.com/mcp"
http_headers = { "Authorization" = "Bearer <jwt-token>" }

Transports, endpoints and STDIO mode: Getting Started.

Under the hood

TypeScript (ESM) on Node.js ≥ 20, built on fa-mcp-sdk — server core, transports, auth, Swagger and Agent Tester come from the SDK. Routing is Yen's k-shortest-paths over a weighted graph rebuilt for the requested moment; the routing, search and widget layers are city-agnostic and simply receive the dataset of the requested city. Data lives in JSON on disk — no database.

License

MIT © Michael Makarova. See LICENSE.