Metadata-Version: 2.4
Name: mcp-deutsche-bahn
Version: 0.1.0
Summary: MCP server exposing live Deutsche Bahn data: journeys, delays, disruptions, strikes, and alternative routes.
Project-URL: Homepage, https://github.com/heykay/mcp-deutsche-bahn
Project-URL: Issues, https://github.com/heykay/mcp-deutsche-bahn/issues
Author-email: Heykay <akhinoz@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,db,deutsche-bahn,hafas,mcp,trains
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.104.0
Requires-Dist: feedparser>=6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.9
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-deutsche-bahn

An MCP server that gives any MCP-compatible AI assistant (Claude Desktop, Claude Code, Cursor, etc.) live access to Deutsche Bahn data: journey planning, real-time delays, disruptions, construction works, strikes, and alternative routes.

> Status: **v0.1.0 — alpha.** Backed by the open [`transport.rest`](https://v6.db.transport.rest/) API — **no API key required.**

## What it does

Six tools, available to your LLM:

| Tool                  | Answers                                                        |
|-----------------------|----------------------------------------------------------------|
| `search_journeys`     | "How do I get from Berlin Hbf to München Hbf tomorrow at 9am?" |
| `station_departures`  | "What's leaving Hamburg Hbf in the next hour?"                 |
| `journey_status`      | "Has my booked journey been delayed?"                          |
| `get_disruptions`     | "Any construction on the Köln–Frankfurt corridor?"             |
| `detect_strike`       | "Is there a strike going on right now?"                        |
| `find_alternatives`   | "Route me around Hannover Hbf if it's blocked."                |

---

## Quickstart (3 steps, ~2 min)

You need **Python 3.10+** and [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (one-line install: `curl -LsSf https://astral.sh/uv/install.sh | sh`).

```bash
# 1. Clone & install
git clone https://github.com/heykay/mcp-deutsche-bahn.git
cd mcp-deutsche-bahn
uv sync

# 2. Sanity-check the server starts
uv run mcp-deutsche-bahn --help 2>&1 | head -1 || echo "server module loaded ✓"

# 3. Note the full path — you'll paste it into the config below
pwd
```

Then wire it into your MCP client (pick one):

### Claude Desktop

Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Add:

```json
{
  "mcpServers": {
    "deutsche-bahn": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/FROM/STEP-3",
        "run",
        "mcp-deutsche-bahn"
      ]
    }
  }
}
```

Restart Claude Desktop. A tool icon appears in the input bar → click → confirm `deutsche-bahn` is listed.

### Claude Code

```bash
claude mcp add deutsche-bahn -- uv --directory /ABSOLUTE/PATH/FROM/STEP-3 run mcp-deutsche-bahn
```

### Cursor / other MCP clients

Same shape — `command: uv`, `args: ["--directory", "<path>", "run", "mcp-deutsche-bahn"]`.

---

## Try it

Ask your assistant:

> What are my options getting from Berlin Hbf to Munich tomorrow at 8am, and is there any construction on that route?

It will call `search_journeys` and `get_disruptions` and stitch a human answer.

---

## Optional: standalone CLI agent

If you want a plain-English REPL without Claude Desktop, the project also ships an `anthropic`-powered front-end that drives the MCP server directly:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
uv run mcp-deutsche-bahn-agent                              # interactive
uv run mcp-deutsche-bahn-agent "next trains out of Hamburg" # one-shot
```

---

## Configuration

| Env var              | Default                         | Purpose                                                  |
|----------------------|---------------------------------|----------------------------------------------------------|
| `DB_TRANSPORT_API`   | `https://v6.db.transport.rest`  | Point at a self-hosted `transport.rest` for reliability. |
| `ANTHROPIC_API_KEY`  | _(unset)_                       | Only needed for the optional CLI agent above.            |

---

## Local development

```bash
uv sync --extra dev
uv run pytest -m live   # smoke tests, hit the real API
uv run ruff check .
```

Run the server in inspector mode to poke individual tools without an MCP client:

```bash
npx @modelcontextprotocol/inspector uv run mcp-deutsche-bahn
```

---

## Known limits

- **Community backend.** `transport.rest` is an open wrapper around DB data, not an official DB product. The public instance has no uptime SLA and rate-limits. For reliability, self-host (Docker image available) and point `DB_TRANSPORT_API` at it.
- **Strike detection is heuristic.** There is no machine-readable "is there a strike?" API. The tool stacks signals from route remarks and DB's construction RSS feed and returns a confidence score. Confirm via [bahn.de/service/aktuell](https://www.bahn.de/service/aktuell), [GDL](https://www.gdl.de/), or [EVG](https://www.evg-online.org/) before acting.
- **Read-only.** Tells you about journeys; doesn't buy tickets.
- **Station resolution is best-effort.** "Berlin Hbf" is reliable; "berlin" picks the first match. Be specific for edge cases.

## Roadmap

- v0.2: hosted/remote MCP variant (HTTP + SSE) for non-CLI users
- v0.2: richer strike signal — wire to a real news API
- v0.3: ticket-price comparison via DB API Marketplace

## Contributing

PRs welcome. File issues with the query that broke and the JSON the tool returned.

## License

MIT — see [LICENSE](LICENSE).
