korea-transit-mcp-server

한국어 문서 (Korean)

MCP server for Korean public transit — route search, real-time bus/subway arrival, congestion data, and more for the Seoul metropolitan area.

Combines ODsay LAB (nationwide route search) with Seoul Open Data (real-time arrivals & congestion) so AI assistants can answer questions like "How do I get from Gangnam to Pangyo right now?"

Tools

Tool	Description
transit_route	Search transit routes between two locations
station_search	Search for bus stops and subway stations by name
line_info	Get route/line details (stops, schedule)
nearby_stations	Find nearby stations by coordinates
bus_arrival	Real-time bus arrival times at a stop
bus_location	Real-time GPS tracking of buses on a route
subway_arrival	Real-time subway arrival times at a station
subway_congestion	Subway congestion statistics by time slot
first_last_train	First/last train schedule for a station

Prerequisites

You need API keys from three providers (all free tier):

Provider	Sign Up	Purpose
ODsay LAB	lab.odsay.com	Route search, station/stop lookup
Seoul Bus API	data.go.kr	Real-time bus arrival & position
Seoul Subway API	data.seoul.go.kr	Real-time subway arrival & congestion

Installation

Claude Code / Claude Desktop

Option 1: Published Package

Add to your MCP configuration:

{
  "mcpServers": {
    "korea-transit": {
      "command": "uvx",
      "args": ["korea-transit-mcp-server"],
      "env": {
        "ODSAY_API_KEY": "your_odsay_key",
        "SEOUL_BUS_API_KEY": "your_data_go_kr_key",
        "SEOUL_SUBWAY_API_KEY": "your_data_seoul_key"
      }
    }
  }
}

Option 2: Local Repository (Development)

Clone the repository and run locally:

1. Clone and Install

git clone https://github.com/SimDaSong/korea-transit-mcp-server.git
cd korea-transit-mcp-server
uv pip install -e .

2. Configure MCP

Copy .mcp.json.example to .mcp.json and add your API keys:

{
  "mcpServers": {
    "korea-transit": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "korea-transit-mcp-server"],
      "env": {
        "ODSAY_API_KEY": "your_odsay_key",
        "SEOUL_BUS_API_KEY": "your_data_go_kr_key",
        "SEOUL_SUBWAY_API_KEY": "your_data_seoul_key"
      }
    }
  }
}

Local Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest -v

# Run the server manually
ODSAY_API_KEY="your_key" \
SEOUL_BUS_API_KEY="your_key" \
SEOUL_SUBWAY_API_KEY="your_key" \
uv run korea-transit-mcp-server

Usage Examples

Route Search

"How do I get from Gangnam Station to Pangyo Station?"

Calls transit_route(start="강남역", end="판교역")

Real-time Bus Arrival

"When is the next bus at stop 22009?"

Calls bus_arrival(ars_id="22009")

Subway Arrival

"When is the next train at Gangnam Station?"

Calls subway_arrival(station_name="강남")

Congestion

"How crowded is Gangnam Station on Line 2?"

Calls subway_congestion(line_num="2", station_name="강남")

API Rate Limits

• ODsay: 1,000 calls/day on free tier (auto-tracked with warnings)
• Seoul Bus/Subway: Public data, generally generous limits

Tech Stack

• Python 3.11+ / FastMCP (official MCP SDK)
• httpx (async HTTP client)
• uv (package management)

License

MIT