# korea-transit-mcp-server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

> [한국어 문서 (Korean)](./README-ko.md)

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](https://lab.odsay.com/) | Route search, station/stop lookup |
| **Seoul Bus API** | [data.go.kr](https://www.data.go.kr/) | Real-time bus arrival & position |
| **Seoul Subway API** | [data.seoul.go.kr](https://data.seoul.go.kr/) | Real-time subway arrival & congestion |

## Installation

### Claude Code / Claude Desktop

#### Option 1: Published Package

Add to your MCP configuration:

```json
{
  "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**
```bash
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:

```json
{
  "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

```bash
# 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](https://github.com/jlowin/fastmcp) (official MCP SDK)
- [httpx](https://www.python-httpx.org/) (async HTTP client)
- [uv](https://docs.astral.sh/uv/) (package management)

## License

MIT
