carris-metropolitana-mcp
This deprecated MCP server provides read-only, no-key, real-time Carris Metropolitana bus data for Greater Lisbon.
Find stops by name, 6-digit stop ID, or coordinates, including distance, serving lines, and wheelchair boarding.
Get upcoming arrivals at a stop, optionally filtered by line, marked realtime or scheduled with minutes from now.
Look up line details: route ends, directions, municipalities/localities, ordered stops, trips today, and first/last departures.
Retrieve active or upcoming service alerts filtered by line or stop, with a language preference.
View live vehicle GPS positions for a line, including heading, speed, headsign, current/next stop, and fix age.
All times are Europe/Lisbon; failures return an error object instead of raising.
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., "@carris-metropolitana-mcp when is the next bus at Gare do Oriente?"
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.
carris-metropolitana-mcp
Deprecated — use portugal-mcp instead. This server now lives on as the transportes feature of portugal-mcp, together with IPMA weather, INE, Banco de Portugal, Parliament, public contracts and more. Install with uvx portugal-mcp (add PORTUGAL_MCP_FEATURES=transportes to load only this part). Tool names: find_stops, next_arrivals, line_info, service_alerts, vehicle_positions → bus_find_stops, bus_next_arrivals, bus_line_info, bus_service_alerts, bus_vehicle_positions. This repository gets no further updates.
MCP server for Carris Metropolitana, the bus network of Greater Lisbon (Lisbon Metropolitan Area), so Claude (or any MCP client) can answer "when is the next bus at X?", "where does line 4715 go?" or "is my line disrupted?" in real time.
Read-only, no key, no account. It only reads the official open API. Not affiliated with Carris Metropolitana or TML (Transportes Metropolitanos de Lisboa).
Note: buses inside the city of Lisbon are mostly run by Carris, a different company that this server does not cover. Carris Metropolitana serves the surrounding municipalities and the routes into Lisbon (e.g. from Oriente, Cacilhas, Setúbal).
Tools
find_stops
Find stops by name and/or near a coordinate. Use it first to get a stop_id.
Parameters:
query— text in the stop name, accent/case-insensitive (e.g."Gare do Oriente","cacilhas terminal"); a 6-digit stop id also workslat/lon— a coordinate; results are sorted by straight-line distanceradius_m— only stops within this radius (default 500 m when noqueryis given)limit— max stops (default 10, max 50)
Each stop has: id, name, locality, municipality, distance, coordinates, the lines serving it, and wheelchair boarding.
next_arrivals
Upcoming buses at a stop, with minutes from now. Each arrival is marked "realtime" (live GPS estimate, with delay vs. timetable) or "scheduled" (timetable only).
Parameters:
stop_id— 6-digit stop id (e.g."060361")line_id— optional, keep only one line (e.g."2794")limit— max arrivals (default 10, max 50)
line_info
A line's name, municipalities and localities served, and each direction (headsign, first and last stop, number of stops, trips today, first/last departure today). Pass a line number ("4715") or text ("Oriente Setubal"), in which case matching lines are listed. include_stops=True adds the ordered stop list for each direction.
service_alerts
Active (and, by default, upcoming) service alerts: detours, works, strikes, stops not served. Filter by line_id and/or stop_id. Alerts are mostly published in Portuguese.
vehicle_positions
Live positions of the buses currently running on a line: coordinates, heading, speed, headsign, the stop it is at or heading to, and how old the GPS fix is.
All times are Europe/Lisbon. On failure a tool returns {"error": "..."} instead of raising.
Related MCP server: Movilidad Con Prompts
Install
Quickest (needs uv): no clone needed, it runs straight from PyPI.
claude mcp add carris-metropolitana -- uvx carris-metropolitana-mcpFor Claude Desktop, use "command": "uvx", "args": ["carris-metropolitana-mcp"].
From source:
Requires Python 3.10+.
git clone https://github.com/ThiagoJacobLannes/carris-metropolitana-mcp
cd carris-metropolitana-mcp
python -m pip install -e .On Windows, if you keep code in a cloud-synced folder (Google Drive, OneDrive), create the virtual environment outside it: sync clients drop desktop.ini files into folders, which can crash packages on startup.
Add to Claude Code
claude mcp add carris-metropolitana -- python -m carris_metropolitana_mcp.serverAdd to Claude Desktop
Merge claude_desktop_config.snippet.json into your Claude Desktop claude_desktop_config.json, then restart Claude Desktop:
{
"mcpServers": {
"carris-metropolitana": {
"command": "python",
"args": ["-m", "carris_metropolitana_mcp.server"]
}
}
}Data source
All data comes from the official Carris Metropolitana open API, https://api.carrismetropolitana.pt/v2 (docs, source). It is public, needs no key, and is the same API the operator's own website and apps use. Carris Metropolitana publishes it as open data; its documentation does not state a specific data licence, so check their terms before redistributing the data itself.
The large, slow-changing lists (all ~12,000 stops, ~700 lines, localities, municipalities) are downloaded once and cached in memory for 12 hours; alerts and vehicle positions are cached for 30 seconds. Set CARRIS_METROPOLITANA_BASE_URL to point at a different API base URL.
Real-time estimates only exist for buses that are already running with live tracking; other arrivals are the published timetable. Arrivals cover the current service day only, so late at night the list can be short.
This project is not affiliated with, endorsed by, or connected to Carris Metropolitana or TML.
License
MIT
Available Tools
5 toolsfind_stopsA
Find Carris Metropolitana bus stops by name and/or near a coordinate.
Use this first whenever the user names a place, street, station or gives a location, to get the stop_id needed by next_arrivals. Results include the lines serving each stop.
Args: query: Text to match in the stop name (accent/case-insensitive, all words must match), e.g. "Gare do Oriente", "Cacilhas terminal". A 6-digit stop id also works. lat, lon: A coordinate (WGS84). Results are sorted by straight-line distance from it. Note: buses inside Lisbon city are mostly run by Carris (a different company, not covered here); Carris Metropolitana serves the wider region. radius_m: Only stops within this many metres of lat/lon. Default 500 when no query is given; unlimited when a query is given. limit: Max stops to return (default 10, max 50).
Inputs: lat, lon, limit, query, +1 more. Returns: object
line_infoA
Details of a Carris Metropolitana line: name, route ends, directions, municipalities.
Use for "where does line 4715 go?", "which bus goes from Cacilhas to Almada?", or to check
whether a line passes a stop (include_stops=True). If line is not an exact line number it
is treated as text (e.g. "Oriente Setubal") and the matching lines are listed instead.
trips_today = 0 means the line does not run today (some lines are seasonal or weekday-only).
Departure times past midnight are written "24:30", "25:10" (same service day).
Args: line: 4-digit line number ("4715") or free text matched against line names. include_stops: Also list every stop (id + name) in order for each direction.
Inputs: line (required), include_stops. Returns: object
next_arrivalsA
Upcoming buses at a Carris Metropolitana stop, real-time where available.
Use for "when is the next bus at X?" (get stop_id from find_stops first). Each arrival says whether it is "realtime" (live GPS estimate) or "scheduled" (timetable only: the bus may not have started its trip yet). minutes_from_now uses the real-time estimate when present. Times are Europe/Lisbon. Only today's operational day is covered, so late at night the list may be short or empty.
Args: stop_id: 6-digit stop id, e.g. "060361". line_id: Optional 4-digit line number to keep only that line, e.g. "2794". limit: Max arrivals to return (default 10, max 50).
Inputs: stop_id (required), limit, line_id. Returns: object
service_alertsA
Service alerts (detours, works, strikes, stops not served) for Carris Metropolitana.
Use before recommending a trip, or when the user asks "is line X disrupted?". Filter by line and/or stop; with no filter, returns all current alerts (there are often ~100). Alerts are mostly published in Portuguese only.
Args: line_id: 4-digit line number, e.g. "4407". stop_id: 6-digit stop id, e.g. "160584". include_upcoming: Also return alerts that start in the future (default True). language: Preferred language ("pt" or "en"); falls back to what exists. limit: Max alerts to return (default 20, max 100).
Inputs: limit, line_id, stop_id, language, +1 more. Returns: object
vehicle_positionsA
Live GPS positions of the buses currently running on a Carris Metropolitana line.
Use for "where is the 3508 right now?" or to see how many buses are out on a line. Each vehicle includes its position, heading, speed, the stop it is at / heading to, and how many seconds old the fix is.
Args: line_id: 4-digit line number, e.g. "3508".
Inputs: line_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct resource: stop discovery (find_stops), real-time arrivals (next_arrivals), line metadata (line_info), disruptions (service_alerts), and live vehicle tracking (vehicle_positions). The descriptions even prescribe the intended workflow (find_stops → next_arrivals), leaving almost no room for misselection.
All names are snake_case, lowercase, and readable, with a mostly noun-phrase convention (line_info, service_alerts, vehicle_positions). Only find_stops is verb-led and next_arrivals is adjective-led, so the pattern isn't perfectly uniform, but it is predictable enough to navigate.
Five tools is a tight, well-scoped surface for a transit data server, and each one covers a genuinely different query type. No tool feels redundant or like filler.
The surface covers the core lifecycle: locate a stop, get arrivals, inspect a line, check disruptions, and track vehicles. Gaps remain around journey planning between two points and timetables for future days (only today's operational day is covered), but these are documented limits rather than dead ends agents can't work around.
Maintenance
Related MCP Connectors
Get real-time NYC bus arrivals, live vehicle locations, and service alerts. Plan trips between any…
Real-time SF Muni departures, routes, alerts, vehicle positions, and schedules.
Live TTC, Hamilton HSR, GO Transit and UP Express stops, departures, alerts and vehicle positions.
Read-only public transit departures, stop search, and city coverage for bus and train users.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAccess bus stops, routes, and real-time information for Porto Alegre's public transportation system.3MIT
- FlicenseNot gradedqualityDmaintenanceProvides real-time and scheduled bus information for Montevideo's public transport system.1-
- AlicenseNot gradedqualityDmaintenanceEnables natural language queries for Porto Alegre's public transport system, including route planning, stop search, and route information via Claude Desktop or any MCP-compatible client.MIT
- AlicenseAqualityDmaintenanceProvides Estonian public transport timetables, trip planning, stop search, and real-time vehicle tracking.81MIT