Skip to main content
Glama
carris-metropolitana-mcp

carris-metropolitana-mcp

carris-metropolitana-mcp

WARNING

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 works

  • lat / lon — a coordinate; results are sorted by straight-line distance

  • radius_m — only stops within this radius (default 500 m when no query is 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-mcp

For 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.server

Add 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 tools
find_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

    A4.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers