# odpt — Japan rail timetables and live train/service status (ODPT)

Japan train timetables and live train information from ODPT (Public
Transportation Open Data Center): station lookup in English or Japanese,
scheduled station and train timetables, and live service status (normal /
delayed / suspended) for Tokyo Metro, JR East, Toei and many other Japanese
railway operators.

Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1875+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

## Tools

| Tool | What it does |
|---|---|
| `odpt_resolve_station` | Find a station by name in English or Japanese ("Shinjuku" / "新宿"). ODPT has no name-search endpoint, so this fetches station master data for one operator (or a short default list of major Tokyo operators) and matches client-side; returns one or more station ids, since a station can belong to several operators/railways. |
| `odpt_station_timetable` | Scheduled departures at a station: destination, time, train type, calendar (weekday/Saturday/holiday). Resolves a plain station name for you if you don't already have an exact station id. |
| `odpt_train_timetable` | Stop-by-stop schedule for one train run, by railway + train number. |
| `odpt_service_status` | Current line status — normal / delayed / suspended — with the operator's own status text in Japanese and English and when it last changed. |

## Auth

Every tool takes an optional `_apiKey`. **Pipeworx supplies an ODPT developer
consumer key for you** (`PLATFORM_ODPT_KEY`, stored in the gateway's encrypted
platform-key store, not as an individual Worker secret — see
`docs/gateway-text-binding-limit.md`), sent upstream as the `acl:consumerKey`
query parameter (that is literally the parameter name ODPT's own 403 names).
Pass your own key via `_apiKey` if you'd rather use your own registration —
sign up at `https://developer.odpt.org/signup` (English:
`https://developer.odpt.org/en/signup`, note: account approval is manual, not
instant), then issue a key once logged in.

## Coverage: the authenticated host only

ODPT's production API gates every class behind `acl:consumerKey`, with no
exception — verified live against an unfiltered operator list, station
lookups for three operators, and even the RDF-type listing, all HTTP 403
`Require acl:consumerKey.`. A separate keyless host exists but only ever
serves one operator (confirmed live: an unfiltered station query returns 149
rows, all Tokyo's Toei bureau; filtering to Tokyo Metro returns HTTP 200 with
an empty array — a silent-zero success, not real coverage) and is not used
here even as a fallback: a keyless 200-with-nothing would make this pack look
alive while actually serving nothing for Tokyo Metro, JR East or live status —
the three things most callers actually want.

## Licence

ODPT publishes this data under its own **Public Transportation Open Data
Basic License** (the licence linked from the data catalog's Tokyo Metro
station/timetable entries). Summarized from the licence text at
`https://developer.odpt.org/terms/data_basic_license.html` (read in full
there before building anything that redistributes this data further):

- Data may be used, combined and built on, for-profit or nonprofit, inside a
  "Deliverable" (an app, dataset or document) that is released to the public.
- Raw data may not be displayed or redistributed outside that Deliverable —
  no "release, redistribute, publicly transmit, or assign" of the data, its
  duplicates, or a derivative that would let a third party reconstruct the
  original. This pack only ever calls the keyed API live, per caller request
  (a proxy, not a mirror), so it ships under the same
  proxy-is-not-redistribution basis as the rest of the Pipeworx catalog —
  nothing here bakes or bulk-downloads ODPT's dataset.
- A Deliverable must tell its users that ODPT and the data providers make no
  warranty on accuracy, and must carry its own contact channel so inquiries
  go to the Deliverable's operator, not directly to the railway operators.
- Using the data must not create "disadvantage or a bad reputation" for ODPT,
  its association, or the data providers.

This pack is a live proxy to the keyed ODPT API on a caller's behalf; it is
not itself the Deliverable, and does not speak for how any caller's own
application uses the results.

## Traps

- **Name resolution costs upstream calls.** ODPT has no title-search
  endpoint — `odpt_resolve_station` fetches each operator's full station list
  and filters client-side. Passing an `operator` narrows it to one upstream
  call; omitting it fans out across a default list of major Tokyo operators.
- **Operator/railway ids are not obvious strings.** `odpt.Railway:<operator
  id>.<line name>`, e.g. `odpt.Railway:TokyoMetro.Marunouchi` or
  `odpt.Railway:JR-East.Yamanote` — the pack's `odpt_service_status` builds
  this from a plain line name only when both `railway` and `operator` are
  given; pass the exact id directly if you already have it.
- **A station can have more than one id.** Stations served by multiple
  operators/lines (e.g. several lines meeting at one named station) have one
  `odpt:Station` row per operator/railway that serves them; `odpt_resolve_station`
  returns all of them, not one canonical row.
- **Live status changes fast; timetables don't.** `odpt_service_status` is
  cached for 60 seconds; the other three tools, which answer from a published
  schedule rather than a live feed, are cached for an hour.

## Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "odpt": {
      "url": "https://gateway.pipeworx.io/odpt/mcp"
    }
  }
}
```

### What this endpoint actually serves

`tools/list` at `https://gateway.pipeworx.io/odpt/mcp` returns the tools in the table
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
gateway-wide set. So the tool count you see is larger than this table: a
single-pack endpoint currently lists roughly 30 shared tools alongside the
pack's own. The connection's `initialize` response states its exact scope, and
is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a
scoped connection answer a question this pack does not cover — via
`ask_pipeworx`, which routes across the whole catalog — without you adding a
second MCP server. There is currently no way to mount a pack endpoint without
them; if the extra schemas cost you more context than the routing is worth,
connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed
directly, instead of just this one's:

```json
{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}
```

Both URLs reach the same gateway and the same 1875+ data sources. The
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
reaches all of them from either one.

## No MCP client? Call it over HTTP

```bash
curl -X POST https://gateway.pipeworx.io/v1/tools/odpt_resolve_station \
  -H 'Content-Type: application/json' \
  -d '{"query":"Hakusan","operator":"Toei"}'
```

No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/odpt_resolve_station`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.

## Run it from npm

`@pipeworx/mcp-odpt` is a local stdio bridge to the Pipeworx gateway: your MCP client
starts it with `npx`, and it forwards every call to the same
`https://gateway.pipeworx.io/odpt/mcp` endpoint shown above. It needs network access;
there is no offline mode.

```json
{
  "mcpServers": {
    "odpt": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-odpt"]
    }
  }
}
```

Without a key it calls anonymously, capped at 50 calls a day. A free account
raises that to 200 a day: get a key at https://pipeworx.io/signup and add
`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
The key is sent as a Bearer token, the same way a hosted connection sends it,
so calls are metered and billed exactly as they are there.

It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
also list `ask_pipeworx` and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
your Node version's documentation.

## Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English —
this works on the pack endpoint above as well as on the full gateway:

```
ask_pipeworx({ question: "your question about Odpt data" })
```

The gateway picks the right tool and fills the arguments automatically.

## More

- [Docs and guides](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)

## License

MIT