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.

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.

Related MCP server: mcp-sbb-transport

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:

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

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.