How do I use Transitous MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Transitous MCP Server find stations near Berlin Hauptbahnhof" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Transitous MCP Server

by Movm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

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.

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:

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.

Available Tools

4 tools

execute_api_actionExecute a Transitous API actionA

Read-onlyIdempotent

Execute one read-only operation from the allowlisted Transitous/MOTIS action catalog. Supports every documented GET and computational POST operation; arbitrary URLs and undocumented parameters are rejected. Use search_api_actions to obtain the action ID and parameter fields. Large responses may be truncated. API documentation: https://transitous.org/api/ OpenAPI: https://github.com/motis-project/motis/blob/v2.10.2/openapi.yaml Usage warning: Transitous is a volunteer-run, best-effort service intended for FOSS and non-profit use. Use a descriptive User-Agent with contact details, cache results, avoid heavy traffic, and contact Transitous before resource-intensive or commercial use.

ParametersJSON Schema

Name	Required	Description
`body`	No	JSON object for POST actions; omit for GET actions
`query`	No	Documented query parameters; arrays are encoded as comma-separated values
`actionId`	Yes	Allowlisted action ID returned by search_api_actions
`maxResponseBytes`	No	Maximum response bytes returned through MCP; narrow large map queries when possible
`acknowledgeHeavyRequest`	No	Required for actions marked resourceIntensive after reviewing the Transitous usage policy

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds context beyond annotations: mentions support for GET and computational POST, rejection of arbitrary URLs, truncation of large responses, and usage policy. However, the mention of POST operations may cause confusion with the read-only annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with purpose first, then details and warnings. While slightly long, every sentence adds value. Could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers allowed operations, truncation, and usage policy, but lacks information on error handling or response format. Adequate but not exhaustive given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining the purpose of maxResponseBytes (truncation) and acknowledgeHeavyRequest (required for heavy actions), going beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Execute', the resource 'read-only operation from the allowlisted Transitous/MOTIS action catalog', and distinguishes it from sibling tools like search_api_actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly states to use search_api_actions to obtain the action ID and parameter fields. Provides responsible usage warnings and prerequisites, but does not explicitly state when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_api_actionsDiscover Transitous API actionsA

Read-onlyIdempotent

Search or list the complete allowlisted Transitous/MOTIS API action catalog. Returns action IDs, methods, paths, accepted query/body fields, and resource-intensity flags for use with execute_api_action. Read-only. API documentation: https://transitous.org/api/ OpenAPI: https://github.com/motis-project/motis/blob/v2.10.2/openapi.yaml Usage warning: Transitous is a volunteer-run, best-effort service intended for FOSS and non-profit use. Use a descriptive User-Agent with contact details, cache results, avoid heavy traffic, and contact Transitous before resource-intensive or commercial use.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum matching actions
`query`	No	Natural-language capability search; use an empty string to list the catalog

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint; the description adds that it is read-only, what fields are returned, and includes usage warnings about the service. No contradiction with annotations, but could mention error behavior or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, starting with the core purpose and then adding behavioral context and warnings. It is efficient but includes necessary usage guidance without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description details return fields (action IDs, methods, etc.). It includes documentation and OpenAPI links. For a two-parameter tool, this provides adequate context for the agent to understand usage and integration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are fully described in the schema (100% coverage). The description adds useful guidance: 'use an empty string to list the catalog' for query, which enhances schema descriptions. No additional hints for limit beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search or list'), the resource ('complete allowlisted Transitous/MOTIS API action catalog'), and the return fields. It distinguishes this tool from siblings like execute_api_action and search_connections by focusing on API action discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool's role in discovering actions for use with execute_api_action. It includes responsible usage warnings about Transitous being volunteer-run and asks for contact before resource-intensive use, but does not explicitly state when not to use this tool vs. alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_connectionsSearch A to B public transport connectionsA

Read-onlyIdempotent

Plan public transport journeys between two station names using Transitous/MOTIS. Returns legs, transfers, times, available realtime status, tracks, and accessibility fields. It does not sell tickets or guarantee accuracy. Usage warning: Transitous is a volunteer-run, best-effort service intended for FOSS and non-profit use. Use a descriptive User-Agent with contact details, cache results, avoid heavy traffic, and contact Transitous before resource-intensive or commercial use. Policy: https://transitous.org/api/

ParametersJSON Schema

Name	Required	Description	Default
`to`	Yes	Destination station or stop, preferably with city/country
`from`	Yes	Origin station or stop, preferably with city/country
`time`	No	Departure time, or arrival deadline when arriveBy is true; defaults to now
`limit`	No	Maximum number of itineraries returned
`arriveBy`	No	Treat time as the latest desired arrival instead of departure
`language`	No	Language tag such as de, en, or fr	de
`wheelchair`	No	Use wheelchair pedestrian routing for transfers
`maxTransfers`	No	Optional maximum number of transfers
`transitModes`	No	Allowed transit modes; omit to allow all public transport
`requireBikeTransport`	No	Only use transit legs that permit bicycle transport when the feed provides this information

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by listing return details (legs, transfers, times, realtime status, tracks, accessibility) and stating limitations (no ticket sales, accuracy not guaranteed). However, it does not explicitly mention that the tool queries an external service or that rate limits may apply, though the usage warning implies responsible usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise, front-loaded with the primary purpose, and every sentence adds value. It efficiently covers purpose, return values, limitations, and usage policy without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, no output schema), the description covers purpose, return values, limitations, and usage policy. While it does not detail the exact output structure, mentioning 'legs, transfers, times, available realtime status, tracks, and accessibility fields' provides sufficient context. The lack of an explicit output schema is compensated by the description, but some agents might benefit from more structured return info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter already has a description. The tool description does not add additional parameter semantics beyond what is in the schema. Per guidelines, baseline is 3, and no extra information is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Plan public transport journeys between two station names using Transitous/MOTIS.' The verb 'plan' and resource 'journeys' are specific, and the tool clearly distinguishes from siblings like execute_api_action or search_locations which handle generic actions or location lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides clear guidance: 'It does not sell tickets or guarantee accuracy.' It also includes a detailed usage warning about Transitous being volunteer-run, best-effort, and intended for FOSS/non-profit use, with specific instructions on User-Agent, caching, traffic limits, and contacting before intensive use. This effectively tells the agent when and how to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_locationsSearch public transport stopsA

Read-onlyIdempotent

Find Transitous stop IDs and coordinates for a station or stop name. Read-only. Usage warning: Transitous is a volunteer-run, best-effort service intended for FOSS and non-profit use. Use a descriptive User-Agent with contact details, cache results, avoid heavy traffic, and contact Transitous before resource-intensive or commercial use. Policy: https://transitous.org/api/

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of matches
`query`	Yes	Station or stop name, optionally including city or country
`language`	No	Language tag such as de, en, or fr	de

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context about the volunteer-run service and usage policy, enhancing transparency beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with core purpose, then provides policy guidance. Sentences are efficient and informative, though the warning could be slightly condensed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description mentions output types (IDs, coordinates). It covers service nature and policy. Parameters are fully defined in schema, making the description fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add significant detail about parameters beyond the schema; it only mentions the query purpose indirectly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds stop IDs and coordinates for a station or stop name, using specific verbs and resources. It distinguishes from sibling tools like search_connections and execute_api_action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage warnings and policy links, but does not directly compare to siblings or state when not to use. However, the context is clear and responsible.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.2.0Jul 16, 2026
- First observedexecute_api_action
- First observedsearch_api_actions
- First observedsearch_connections
- First observedsearch_locations

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-07-16 22:35 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: discovering actions (search_api_actions), executing them (execute_api_action), planning journeys (search_connections), and finding locations (search_locations). No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (search_api_actions, execute_api_action, search_connections, search_locations). The naming is predictable and intuitive.

Tool Count5/5

Four tools is well-scoped for a transit API server. Each tool covers a core operation: discovery, execution, journey planning, and location lookup. No unnecessary tools, and no missing essential categories.

Completeness4/5

The tool set provides a flexible generic action executor (execute_api_action) that can handle any read-only API endpoint, plus convenience tools for common tasks (search_connections, search_locations). Minor gap: no dedicated departure/arrival board tool, but that can be achieved via execute_api_action.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

swisstransport A
io.github.pipeworx-io
Swiss Transport MCP — wraps Transport Open Data API (free, no auth)
Travel & Transportation Open Data Government Data
342
Live Times Transit
io.github.travelwhiz-ltd
Read-only public transit departures, stop search, and city coverage for bus and train users.
Travel & Transportation Location Services
1
onebusaway-mcp-server A
io.github.cyanheads
Real-time transit stops, routes, arrivals, vehicle positions, and schedules via OneBusAway APIs.
Travel & Transportation Location Services
1521
nominatim-mcp-server
io.github.cyanheads
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Location Services Open Data
25

Related MCP Servers

RMV MCP Server
Travel & Transportation Search
heikoliedtke
F
license
Not graded
quality
D
maintenance
Enables querying nearby stations and departure boards using the RMV public transport API.
Updated 2 months ago (2026-07-16 17:27 UTC)
1
-
mcp-sbb-transport
Travel & Transportation Open Data
McCullonas
F
license
Not graded
quality
D
maintenance
Enables querying Swiss public transport (trains, buses, trams, boats) for stations, connections, and station boards via the opendata.ch API.
Updated 6 months ago (2026-03-14 12:02 UTC)
-
otp-mcp
Travel & Transportation Location Services
ojimpo
F
license
A
quality
C
maintenance
Enables querying self-hosted OpenTripPlanner for accurate transit routes via MCP, supporting both stdio and HTTP.
Updated 2 months ago (2026-07-01 17:41 UTC)
3
-
mcp-mbta
Travel & Transportation Location Services
pipeworx-io
A
license
Not graded
quality
C
maintenance
Enables real-time access to Boston MBTA transit data (subway, bus, commuter rail, etc.) via the MBTA v3 API.
Updated 3 days ago (2026-09-13 07:03 UTC)
1 npm
MIT