Transitous MCP Server

A self-hostable Model Context Protocol server covering the complete public Transitous MOTIS API. It works over Streamable HTTP for ChatGPT, Claude, Grünerator, and other MCP clients, or locally over stdio.

Important: Transitous usage policy

Before deploying this server, read the Transitous API usage policy.

[!WARNING] Nutzungsrichtlinie: Die öffentliche Transitous-API wird ehrenamtlich und nach Best-Effort betrieben. Sie ist für freie/Open-Source-Anwendungen und gemeinnützige Aktivitäten gedacht, nicht standardmäßig für kommerzielle Nutzung. Vor vielen oder rechenintensiven Anfragen muss Transitous kontaktiert werden. Jede Anfrage braucht einen User-Agent mit App-Name, Version und Kontaktmöglichkeit. Quellenangaben und deren Lizenzen müssen sichtbar bleiben.

Transitous is a volunteer-run, best-effort service intended for free/open-source and non-profit use. You must:

• send a meaningful User-Agent containing the application name, version, and contact;
• cache results and avoid unnecessary or resource-intensive requests;
• contact Transitous before heavy, unusual, or commercial use;
• visibly link to Transitous data sources and preserve source-specific attribution, including OpenStreetMap attribution.

This server enforces a descriptive User-Agent, caches stop searches for 15 minutes and routing/generic API responses for 60 seconds, and limits uncached upstream calls to 20 per minute by default. Resource-intensive actions require an explicit policy acknowledgement. These protections do not grant permission beyond the Transitous policy or the individual data-source licences.

Transitous and its feeds may be incomplete, delayed, or incorrect. Do not rely on results as the sole source for critical travel decisions; verify important journeys with the relevant operator.

Tools

• search_locations — resolve station/stop names to Transitous stop IDs.
• search_connections — find A-to-B journeys with legs, transfers, available realtime status, delays, tracks, wheelchair routing, and bicycle requirements.
• search_api_actions — search or list the complete allowlisted API catalog and its accepted query/body fields.
• execute_api_action — execute any operation from that catalog, including computational POST endpoints. Arbitrary URLs are not accepted.

All tools are read-only from the user's perspective. The upstream POST endpoints perform routing computations; they do not create or mutate Transitous data. Reservations and ticket sales are not part of the upstream API. The generic plan action can request experimental fare data with withFares=true when the underlying feeds provide it.

Complete API coverage

The catalog covers all 21 GET/POST operations in the pinned MOTIS 2.10.2 OpenAPI surface used by this release:

Area	Actions
Journey routing	plan, refresh_itinerary_get, refresh_itinerary_post
Reachability	one_to_many_get, one_to_many_post, one_to_many_intermodal_get, one_to_many_intermodal_post, one_to_all
Places	geocode, reverse_geocode
Timetable	trip, stoptimes
Map	map_initial, map_trips, map_stops, map_levels, map_routes_experimental, map_route_details_experimental
Rentals	rentals
Operations/debug	health, debug_transfers

The exact accepted parameters are returned by search_api_actions and validated before any upstream request. Parameter semantics follow the MOTIS OpenAPI document. Experimental endpoints are clearly marked and may change upstream.

Large map and routing responses are limited to 250 kB by default and report when they were truncated. maxResponseBytes can be raised to 1 MB, but narrowing the geographic/time query is preferred. Actions marked resourceIntensive only run with acknowledgeHeavyRequest=true after reviewing the Transitous policy.

Example generic action input for departures:

{
  "actionId": "stoptimes",
  "query": {
    "stopId": "STOP_ID_FROM_SEARCH_LOCATIONS",
    "n": 10,
    "language": ["de"],
    "withAlerts": true
  }
}

Run locally

Requirements: Node.js 20+ and pnpm.

pnpm install
cp .env.example .env
pnpm build
TRANSITOUS_USER_AGENT='my-app/1.0.0 (mailto:me@example.com)' pnpm start

The default transport is stdio. Configure your local MCP client to run:

{
  "mcpServers": {
    "transitous": {
      "command": "node",
      "args": ["/absolute/path/to/transitous-mcp/dist/index.js"],
      "env": {
        "TRANSITOUS_USER_AGENT": "my-app/1.0.0 (mailto:me@example.com)"
      }
    }
  }
}

Remote HTTP / Coolify

Deploy the repository with its Dockerfile, expose port 3000, and set:

MCP_TRANSPORT=http
PORT=3000
TRANSITOUS_USER_AGENT=your-app/1.0.0 (https://your.example/contact; mailto:you@example.com)
MCP_API_KEY=generate-a-long-random-secret
MCP_ALLOWED_ORIGINS=https://chatgpt.com,https://claude.ai

Endpoints:

• MCP: https://your-domain.example/mcp
• Health: https://your-domain.example/health

Send the private key using either header:

Authorization: Bearer YOUR_SECRET

or:

X-API-Key: YOUR_SECRET

Domain/Origin filtering alone is not authentication. For a public internet deployment, use HTTPS and set MCP_API_KEY. This version supports a static Bearer token; OAuth can be added later for per-user authorization.

Configuration

Variable	Required	Default	Purpose
TRANSITOUS_USER_AGENT	For tool calls	none	App name/version/contact required by Transitous
MCP_TRANSPORT	No	stdio	Set http for remote deployment
PORT	No	3000	HTTP port
MCP_API_KEY	Recommended for HTTP	none	Protects the MCP endpoint
MCP_ALLOWED_ORIGINS	No	any	Comma-separated browser origins
TRANSITOUS_BASE_URL	No	https://api.transitous.org	Upstream base URL
TRANSITOUS_REQUESTS_PER_MINUTE	No	20	Per-process uncached upstream safety limit
MCP_REQUESTS_PER_MINUTE	No	60	Per-IP inbound HTTP limit

Development

pnpm check
pnpm test
pnpm build

License

The MCP server code is MIT licensed. Transit data is provided by separate sources with their own licences and attribution requirements. The MIT licence does not apply to, replace, or override those data-source terms.