Content
# naeryeo CLI/MCP
<p align="center">
<img src="./naeryeo.png" alt="naeryeo" width="320">
</p>
naeryeo is a CLI and MCP server that allows you to ask for public transportation routes in South Korea in natural language, compatible with various MCP clients like Claude Desktop and Claude Code.
naeryeo can be used in two ways:
- **Skills & CLI** — Use SKILLS to let the AI agent bring up the context at the right moment (recommended).
- **MCP Server** — Support for stdio MCP server for those more familiar with it.
Both methods require the `naeryeo` binary and ODsay API key.
## 1. Skills & CLI
### 1-1. Installation
**Install SKILL**
Search for naeryeo at [skills.sh](https://skills.sh) or run the following command:
```bash
npx skills add GyeongHoKim/naeryeo
```
Alternatively, copy the SKILL.md from the skills folder and paste it into the desired location.
**Install Binary**
If the SKILL is properly reflected, the AI agent will use the `naeryeo` command as CLI. Before that, install the binary with the following command:
```bash
# For macOS / Linux users (Homebrew)
brew install --cask GyeongHoKim/tap/naeryeo
```
```powershell
# For Windows users (Scoop)
scoop bucket add naeryeo https://github.com/GyeongHoKim/scoop-bucket
scoop install naeryeo
```
```bash
# For npm installation
npm install -g @gyeonghokim/naeryeo
```
You can also download the binary from [GitHub Release](https://github.com/GyeongHoKim/naeryeo/releases) for your platform.
### 1-2. API Key Registration
A ODsay API key is required for route search. Get the app key from [ODsay](https://lab.odsay.com) and then:
```bash
naeryeo setup
```
```
ODsay API Key: ****************
Saved to OS Keychain
```
The API key is stored only in the OS Keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service) and not in plain text files or transmitted externally.
**(Optional) Building Name/Address Search Key** — See 1-4.
### 1-3. Usage
```bash
naeryeo route --from "Gangnam Station" --to "Hongdae Station"
```
```
Gangnam Station → Hongdae Station (about 42 minutes, 1 transfer)
1. Take line 2 from Gangnam Station
2. Transfer to line 2 → Gyeongui-Jungang line at Sindorim Station
3. Get off at Hongdae Station
Fare: 1,500 KRW
```
### 1-4. Search by Building Name/Address (Optional)
The route search engine (ODsay) only recognizes **station names**. For building names or road addresses, a separate location search service is needed.
- **Not needed**: If you only ask with station names like "Gangnam Station" or "Yongsan", this setting is not required.
- **Needed**:
1. Create an application at [Kakao Developers](https://developers.kakao.com) and get a **REST API key**. Activate the **Kakao Maps (Local) service**.
2. Register the key:
```bash
naeryeo setup --geocoder
```
```
Kakao REST API Key: ****************
Saved to OS Keychain
```
The location search key is stored as a **separate item** in the OS Keychain.
3. Now you can search by building name or address:
```bash
naeryeo route --from "XXX Cinema" --to "Gangnam Station"
```
- **Not set**: If you input a building name or address without the location search key, "Not found" will be displayed along with a guide to set the key with `naeryeo setup --geocoder`.
- **Deletion**: You can delete only the location search key with `naeryeo logout --geocoder` (ODsay key remains).
## 2. MCP Server (stdio)
Connect to MCP clients like Claude Desktop and ask for routes in natural language during conversations.
### 2-1. Installation and Key Registration
Binary installation and API key registration are the **same as 1-1 and 1-2** (`naeryeo` binary installation and `naeryeo setup`). If building name/address search is needed, register with `naeryeo setup --geocoder`.
### 2-2. Connection
Add one of the following to `claude_desktop_config.json`:
**If binary is installed** (Homebrew · Scoop · npm global installation — `naeryeo` is in PATH):
```json
{
"mcpServers": {
"naeryeo": {
"command": "naeryeo",
"args": ["mcp"]
}
}
}
```
**If installed locally with npm** (npx):
```json
{
"mcpServers": {
"naeryeo": {
"command": "npx",
"args": ["-y", "@gyeonghokim/naeryeo", "mcp"]
}
}
}
```
Do not put the API key in the config file — reuse the value stored in the OS Keychain with `naeryeo setup`.
### 2-3. Usage
After registration, ask in Claude Desktop:
> "How do I get to Hongdae Station from Gangnam Station by public transportation?"
## Commands
| Command | Description |
| --- | --- |
| `naeryeo setup` | Register ODsay (route search) API key |
| `naeryeo setup --geocoder` | Register location search (Kakao) API key — for building name/address search (optional) |
| `naeryeo logout` | Delete stored ODsay API key |
| `naeryeo logout --geocoder` | Delete stored location search API key |
| `naeryeo route --from <origin> --to <destination>` | Route search (CLI mode) |
| `naeryeo mcp` | Start as MCP stdio server |
| `naeryeo --version` | Check version |
## Architecture
```
naeryeo/
cmd/naeryeo/ # Subcommand entry points (setup, route, mcp)
internal/core/ # Route search logic (ODsay client, common domain model, Geocoder interface)
internal/geocode/ # Location search (geocoding) integration — building name/address → coordinates (Kakao)
internal/config/ # API key storage/retrieval based on OS Keychain (go-keyring)
```
CLI and MCP modes share the same `internal/core` logic, with different entry points.
## Used APIs
- **Public Transportation Route Search**: [ODsay API](https://lab.odsay.com) is used. Kakao and Naver Maps APIs do not support route search directly, and Google Directions API is restricted for domestic route search due to regulations.
- **Building Name/Address → Coordinates (Geocoding, optional)**: Since ODsay lacks this functionality, [Kakao Local Keyword Search](https://developers.kakao.com/docs/latest/en/local/dev-guide) is used to obtain coordinates. This is only for name → coordinate translation and not for route search.
## License
MIT
