# ekigraph 🚉

English | [日本語](README.ja.md)

**An MCP server that lets AI answer questions about Japan's railway network correctly.**
It gives the AI on-the-spot access to which stations are connected by track — all 9,043 stations nationwide.

## Why I built this

When I'm heading out or planning a trip, I often want to know something about train stations.
I could search for it, but that's a hassle — so I just ask an AI.

The problem: when the topic is trains, AI often lies without hesitation.

Here's a case that actually happened.

I asked an AI "which station is next to Shin-Shibaura?", and it replied:

> Shin-Shibaura is a new station on the Tōkaidō Freight Line; the next stop is Hama-Kawasaki.

This is completely false. Shin-Shibaura is on the Tsurumi Line, and its neighbors are Asano and Umi-Shibaura.

The AI didn't say "I don't know." It fabricated an answer, nonexistent railway line included.

For major stations like Shinjuku or Shibuya, the answers are usually accurate.
But for minor stations and local lines like this one, the odds of hallucination go up.

## What you get

Connect ekigraph, and the AI answers from correct data instead of its own memory.

ekigraph is built on open data, so anyone can use it.

- 9,043 stations and 593 lines nationwide — from shinkansen to subways, local private railways, and trams
- The data comes from the Japanese government's official open data (MLIT National Land Numerical Information)
- It ships as a bundled 2 MB file — **no API key, free, works offline**

## How to use

```bash
# Claude Code — one line
claude mcp add ekigraph -- uvx --from git+https://github.com/yataro-fujinaga/ekigraph ekigraph
```

For Claude Desktop or any other MCP client, add this to your config:

```json
{ "ekigraph": { "command": "uvx", "args": ["--from", "git+https://github.com/yataro-fujinaga/ekigraph", "ekigraph"] } }
```

After that, just talk normally and the AI returns correct answers.

Even a casual question like "what was next to Urawa again?" gets a proper answer, backed by ekigraph.

## Tools

- **`neighbors(station)`** — returns the stations connected by track, with line names
- **`subgraph(station, radius)`** — returns the raw track data around a station, as-is

## Out of scope

- Timetables, fares, express-stop patterns, and delay information are **not covered**.
- ekigraph holds one thing only: how the tracks connect.
- Station aggregation (counting Shibuya's JR, Metro, Tokyu and Keio as one station)
  follows MLIT's official cross-operator station group codes.

## About the data

- Source: [National Land Numerical Information (Railway Data, N02-24)](https://nlftp.mlit.go.jp/ksj/)
  by MLIT Japan, processed and redistributed under the Government of Japan
  Standard Terms of Use v2.0 (CC BY 4.0 compatible)
- To rebuild it yourself: `uv run python etl/build_graph_n02.py`
  (downloads the source data, derives the adjacency, and validates it — fully automatic)

## License

Code: MIT. For the bundled data's attribution, see LICENSE.