transit-mcp — 이동비서 MCP (Korean Public Transit MCP Server)

A remote MCP (Model Context Protocol) server for Korean public transit. It helps an AI assistant answer not just "how do I get there?" but "what should I take right now, and what's my fallback if I miss it?" — combining route planning with real-time bus and subway arrivals.

Built for the Streamable HTTP transport with the official @modelcontextprotocol/sdk, stateless and container-ready.

Tools

Tool	What it does	Data source
search_route	Plan a transit route between two places: fastest route with per-leg detail (lines, stops, boarding-stop IDs), total fare, and condition-best alternatives (fewest transfers / cheapest / least walking).	ODsay(오디세이) + keyword geocoding
get_bus_arrival	Real-time bus arrivals at a stop (by name or stop ID): minutes away, stops away, remaining seats, crowding, low-floor; falls back to route headway + last-bus time.	Gyeonggi Bus(경기버스)
get_subway_arrival	Real-time subway arrivals at a station (whole Seoul metro network), with optional line filter: destination/direction, minutes away, current train position.	Seoul Metro(서울 지하철)

Boarding-stop IDs from search_route chain directly into get_bus_arrival, so an assistant can go from "plan the route" to "is the next bus coming in time?" in one flow.

Endpoint

• Transport: Streamable HTTP (stateless)
• Path: POST /mcp
• Health check: GET /health
• Protocol version: 2025-03-26

Running locally

npm install
cp .env.example .env    # fill in the API keys
npm run build
npm start               # serves on :8080/mcp

Or in dev mode with reload:

npm run dev

Docker

docker build --platform linux/amd64 -t transit-mcp .
docker run --env-file .env -p 8080:8080 transit-mcp

Environment variables

Variable	Purpose
KAKAO_REST_KEY	Local keyword geocoding (place → coordinates)
ODSAY_API_KEY	ODsay public-transit route search
ODSAY_REFERER	Referer header required by the domain-registered ODsay key
GYEONGGI_BUS_SERVICE_KEY	Gyeonggi bus real-time arrivals
SEOUL_SUBWAY_ARRIVAL_KEY	Seoul subway real-time arrivals
PORT	HTTP port (default 8080)

Coverage & notes

• Route search covers the Seoul metropolitan area.
• Real-time bus data covers Gyeonggi Province stops (Seoul city buses are a planned addition via a nationwide bus API).
• Real-time subway data covers the entire Seoul metropolitan subway network.
• Tool responses are curated Korean text (not raw API dumps) to stay compact.

License

MIT