STPT MCP
STPT MCP is an unofficial read-only MCP server for Timișoara public transport, exposing live and schedule transit data through seven tools over stdio or Streamable HTTP.
Search stops by ID, name, or line with diacritic-insensitive matching.
Get stop details: coordinates, serving lines, directions, terminals, and neighboring stops.
List tram, trolleybus, bus, metropolitan, express, and vaporetto routes.
Get upcoming arrivals with line/limit filters, live-first behavior, GTFS schedule fallback, and explicit freshness/provenance metadata.
Get current or historical service alerts filtered by stop, line, and active status.
Get vehicle positions with line filters, observation timestamps, and staleness flags.
Check server readiness, version, network feed metadata, live-feed freshness, and cache statistics.
Use bundled offline stop/route discovery, structured errors, and secure HTTP options including bearer auth and OAuth sign-in.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@STPT MCP When is the next tram at Piața Sfânta Maria?"
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.
STPT MCP
An unofficial, standalone Model Context Protocol server for STPT public transport in Timișoara, Romania. It exposes live arrivals, date-aware schedule fallback, service alerts, vehicle positions, and an offline stop/route index to MCP clients over stdio or Streamable HTTP.
This project is not affiliated with, endorsed by, or operated by STPT or the Timișoara municipality. Upstream data is used with caching and conservative request limits. Do not use it for safety-critical decisions.
In action

Ask in plain language. The assistant calls search_stops to resolve the stop,
then get_arrivals for the departures, and answers with the next bus. The same
tools work from any MCP client — Claude, Hermes, Cursor, or an agent of your
own.
Related MCP server: @cyanheads/onebusaway-mcp-server
Highlights
Seven read-only MCP tools with typed output schemas.
Live-first arrivals with date- and shape-aware schedule fallback, explicit provenance, and last-known-good stale data.
Bounded TTL caches with single-flight refresh. Fifty concurrent calls to one stop produce one live upstream request, not fifty.
Bounded upstream concurrency, timeouts, retries with jitter,
Retry-Aftersupport, and response-size limits.Bundled GTFS-derived network snapshot, so stop/route discovery works offline.
stdio and Streamable HTTP through the official MCP Python SDK.
Secure HTTP defaults: loopback bind, DNS-rebinding protection, Host/Origin validation, body limits, bounded sessions/concurrency, optional bearer auth, and built-in OAuth 2.1 sign-in for hosted clients.
Deterministic test suite with real MCP client tests for stdio and HTTP.
Requirements
Python 3.11 or newer.
uv for development (optional for end users).
Network access to STPT endpoints for live data. Discovery tools work offline.
Install
From PyPI, with one command:
pip install stpt-mcp
stpt-mcp --versionOr run it without installing anything permanently, using uv:
uvx stpt-mcp --versionFrom a checkout:
uv sync --all-groups
uv run stpt-mcp --versionOr from a wheel/sdist:
python -m venv .venv
. .venv/bin/activate
pip install dist/stpt_mcp-0.3.7-py3-none-any.whl
stpt-mcp --versionstpt-mcp with no subcommand is equivalent to stpt-mcp serve and defaults to
stdio.
Quick start
stdio
uv run stpt-mcp serve --transport stdioThe simplest MCP client configuration lets uvx fetch the package from PyPI
on first use:
{
"mcpServers": {
"stpt": {
"command": "uvx",
"args": ["stpt-mcp", "serve", "--transport", "stdio"]
}
}
}A minimal MCP client configuration using an installed console script:
{
"mcpServers": {
"stpt": {
"command": "stpt-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}From a checkout without installing the script:
{
"mcpServers": {
"stpt": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/stpt-mcp",
"stpt-mcp",
"serve",
"--transport",
"stdio"
]
}
}
}The server writes logs to stderr and never writes protocol data to stdout.
Streamable HTTP
uv run stpt-mcp serve --transport http
# endpoint: http://127.0.0.1:8000/mcp
# health: http://127.0.0.1:8000/healthzGenerate a bearer token for any non-local deployment:
export STPT_MCP_AUTH_TOKEN="$(stpt-mcp token)"
stpt-mcp serve --transport httpClients then send Authorization: Bearer <token>. /healthz stays
unauthenticated.
For hosted clients that support OAuth, set a public origin and a sign-in password instead of handing out a header token:
export STPT_MCP_PUBLIC_URL=https://mcp.example.com
export STPT_MCP_OAUTH_PASSWORD='replace-with-a-long-random-password'
stpt-mcp serve --transport httpClaude's custom connector can then use Sign in now with Register automatically. See OAuth sign-in for the reverse-proxy paths and connector steps.
Minimal client configuration:
{
"mcpServers": {
"stpt": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}HTTP is bound to 127.0.0.1 by default. Binding elsewhere requires an explicit
STPT_MCP_ALLOWED_HOSTS allowlist. If you expose the server beyond localhost,
also set STPT_MCP_AUTH_TOKEN and terminate TLS at a reverse proxy. For a
complete public deployment, see Public HTTPS,
OAuth sign-in, Deployment, and
Security.
Tools
Tool | Purpose |
| Search stops by ID, name, or line (diacritic-insensitive). |
| Stop coordinates, lines, directions, destinations, neighbors. |
| Routes with mode, category, and colors. |
| Live arrivals, with schedule fallback and line/limit filters. |
| Service alerts with active-period and stop/line filters. |
| Vehicle positions with observation timestamps and staleness. |
| Readiness, version, feed metadata, cache statistics. |
Every result is a typed envelope. Data-source problems are returned as
status: "partial" or "error" with a structured error, not a traceback:
{
"status": "partial",
"error": {
"code": "upstream_http_error",
"message": "Live arrivals were unavailable; schedule data is being used.",
"retryable": true,
"upstream": "live arrivals"
},
"provenance": {
"source": "schedule",
"fetched_at": "2026-10-21T10:30:00Z",
"observed_at": null,
"is_stale": false,
"data_age_seconds": 0.0,
"fallback_reason": "live_unavailable",
"warnings": ["Live arrivals were unavailable; trying the schedule."]
},
"stop_id": "59",
"stop_name": "Piața Sfânta Maria",
"line_filter": null,
"lookahead_minutes": 180,
"count": 9,
"arrivals": []
}arrivals is abbreviated above. Full schemas are generated from the Pydantic
models and exposed through MCP. See Tools for arguments,
semantics, error codes, and more examples.
Configuration
Configuration is read from environment variables; a few common values also have CLI flags. Defaults are safe for local use.
Variable | Default | Purpose |
|
|
|
|
| HTTP bind address. |
|
| HTTP port. |
|
| Streamable HTTP path. |
|
| Python log level. |
| unset | Optional static bearer token (16+ chars). |
| loopback | Required for non-loopback binds. |
| loopback | Browser origins allowed by the SDK. |
|
| HTTP request body limit in bytes. |
|
| HTTP concurrency cap. |
TTLs, stale windows, upstream timeouts, retry policy, and cache bounds are also configurable. See Configuration for the complete table.
How data selection works
A fresh cached arrival snapshot for the stop is returned with no request.
Otherwise live predictions are fetched. They are used only if their freshness is verified against the real clock: the feed's implied clock must match it, must not stand still across fetches, and must move with real time.
If live is empty, unavailable, stale, or unverified, the departures come from the bundled GTFS timetable for the local service date (
source: "schedule",live: false). No website is contacted for this.If the refresh fails, last-known-good data may be served inside the stale window.
If no usable data remains, the tool returns a structured error. Stale or unverified live predictions are never returned as arrivals, because frozen minutes counted from now look like real departures.
provenance.source identifies live, schedule, or network data;
provenance.is_stale and data_age_seconds quantify freshness;
fallback_reason explains why live data was not used. Live arrivals expose no
upstream observation timestamp, so observed_at is the fetch time for live
arrivals and null for schedules.
Development
uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv run pytest --cov --cov-report=term-missing
uv run bandit -c pyproject.toml -r src
uv run pip-audit
uv buildThe default suite never contacts live STPT services. It uses deterministic
fixtures, injected clocks, httpx.MockTransport, and loopback fake upstreams.
An opt-in live smoke test is available:
STPT_MCP_RUN_NETWORK_TESTS=1 uv run pytest -m networkSee Testing, Architecture, and Contributing.
Related projects
The same STPT data, exposed for different runtimes. If one of these fits your setup, the others probably do too.
Project | Runtime | Use it for |
STPT MCP (this repo) | Any MCP client | Talking to your transport data |
Home Assistant | Automations, sensors, and dashboards | |
Raspberry Pi | A glanceable e-ink departures display |
All three are unofficial and are not affiliated with STPT.
Limitations
Upstream endpoints are unofficial public interfaces and may change without notice.
The bundled network snapshot and timetable are point-in-time GTFS-derived artifacts that end on 2026-12-31; after that the schedule fallback reports
schedule_unavailableuntil a release regenerates them. The feed version and service range are exposed byget_service_status.STPT's live arrivals feed carries no timestamps. Freshness is inferred from its display times, so the first fetch of a stop after a restart cannot prove the feed is running.
Each process has its own in-memory cache; multi-worker deployments do not share entries.
OAuth is single-owner and keeps tokens in memory; a restart requires clients to sign in again. It is not a multi-user identity provider.
Live arrivals do not carry an upstream observation timestamp.
Author
Created and maintained by Vlad Ohai (GitHub).
License and attribution
MIT licensed, © 2026 Vlad Ohai. STPT data remains the property of its respective owners. See LICENSE and NOTICE. OpenStreetMap-derived coordinates, if present, are © OpenStreetMap contributors under the ODbL.
Available Tools
7 toolsget_alertsGet STPT service alertsARead-onlyIdempotent
Get current or historical STPT service alerts. Filters by stop ID and/or line when supplied. Active periods are evaluated in Europe/Bucharest.
Inputs: line, limit, stop_id, active_only. Returns: line, count, error, alerts, +4 more
get_arrivalsGet STPT arrivalsARead-onlyIdempotent
Get upcoming arrivals at an STPT stop. Live data is used only when its freshness is verified; otherwise departures come from the bundled GTFS timetable. Check provenance.freshness, provenance.fallback_reason, and each arrival's live flag.
Inputs: stop_id (required), line, limit. Returns: count, error, status, stop_id, +5 more
get_service_statusGet STPT MCP service statusARead-onlyIdempotent
Report server readiness, version, bundled network feed metadata, and bounded cache statistics. Contains no secrets.
Inputs: no named parameters. Returns: error, ready, caches, status, +9 more
get_stopGet STPT stop detailsARead-onlyIdempotent
Get coordinates, serving lines, directions, terminals, and neighboring stops for a numeric STPT stop ID.
Inputs: stop_id (required). Returns: stop, error, status, provenance
get_vehiclesGet STPT vehicle positionsARead-onlyIdempotent
Get current STPT vehicle positions, optionally filtered by line. Each vehicle includes its upstream observation timestamp and staleness flag.
Inputs: line, limit. Returns: count, error, status, vehicles, +2 more
list_routesList STPT routesBRead-onlyIdempotent
List STPT tram, trolleybus, bus, metropolitan, express, and vaporetto routes from the bundled GTFS-derived network snapshot.
Inputs: mode. Returns: count, error, routes, status, +1 more
search_stopsSearch STPT stopsARead-onlyIdempotent
Search the bundled STPT network by stop ID, stop name, or line. Uses diacritic-insensitive matching. Returns up to 50 stops.
Inputs: query (required), limit. Returns: count, error, query, stops, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct transit object or concern: stop search, stop detail, route listing, arrivals, service status, alerts, and vehicle positions. Boundaries are clear even where arrivals and vehicle positions both relate to live transit data.
All tool names use a consistent snake_case verb_noun convention: search_stops, get_stop, list_routes, get_arrivals, get_service_status, get_alerts, get_vehicles. No ambiguous or inconsistent naming styles appear.
Seven tools is well-scoped for a transit MCP server, covering discovery, detail, arrivals, alerts, vehicles, and health without bloat. Each tool has a clear role.
The surface covers core transit workflows: finding stops, viewing routes and stop details, checking arrivals, alerts, and vehicle positions. Minor gaps exist, such as explicit route-detail or trip-planning operations, but core use cases are supported.
Maintenance
Related MCP Connectors
Transitland MCP — global GTFS aggregator
Read-only public transit departures, stop search, and city coverage for bus and train users.
Official MCP server for MAQAMI, a hotel and flight booking platform with 3M+ hotels. Search live hotel rates and flights, look up places, airports and hotel details, then prebook and book. Remote Streamable HTTP endpoint, no API key required.
Lviv public transport MCP: stops, timetables, routes, and live vehicle positions. No API key.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for Chelaile realtime public transit data in China, including bus and metro arrivals, vehicle positions, nearby stops, timetables, and route planning. It runs locally over stdio with no login or account configuration required.1533,447 npm38MIT
- AlicenseNot gradedqualityBmaintenanceEnables querying stops, routes, real-time arrivals, vehicle positions, and schedules from OneBusAway transit APIs via MCP, supporting STDIO or Streamable HTTP.149 npm2Apache 2.0
- AlicenseAqualityCmaintenancePrivate MCP server adapter for RedTransporteAPI, providing read-only access to Santiago de Chile public transit data including stops, routes, real-time iBus/RED predictions, and RAPTOR journey planning, secured with deny-by-default bearer token authentication over stdio or streamable HTTP.151GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables querying real-time BART and SF Muni transit data, including departures, trip planning, fares, advisories, routes, alerts, vehicle positions, and schedules, from any MCP-compatible client.1MIT