Carris Metropolitana

carris-metropolitana-mcp

Carris Metropolitana 的 MCP 服务，适用于Carris Metropolitana——大里斯本地区（里斯本大都会区）的公交网络，让 Claude（或任何 MCP 客户端）可以实时回答“X 站的下一班公交车几点到？”、“4715 路开往哪里？”或“我乘坐的线路是否受影响？”等问题。

**只读，无需密钥，无需账户。**它只读取官方开放 API。与 Carris Metropolitana 或 TML（Transportes Metropolitanos de Lisboa）无关联。

注意：里斯本市内的公交车大多由 Carris 运营，这是另一家公司，本服务不涵盖。Carris Metropolitana 服务周边市镇以及开往里斯本的线路（例如从 Oriente、Cacilhas、Setúbal 出发的线路）。

工具

find_stops

按名称和／或坐标附近查找站点。首先使用此工具获取 stop_id。

参数：

• query — 站点名称中的文本，不区分重音和大小写（例如 "Gare do Oriente"、"cacilhas terminal"）；也可以使用 6 位数的站点 ID
• lat / lon — 坐标；结果按直线距离排序
• radius_m — 仅返回此半径范围内的站点（未提供 query 时默认为 500 m）
• limit — 最多返回的站点数（默认 10，最多 50）

每个站点包含：ID、名称、地区、市镇、距离、坐标、途经线路以及是否支持轮椅上下车。

next_arrivals

查询站点即将到站的公交车，以及距当前时间的分钟数。每班车都会标记为 "realtime"（实时 GPS 估算，并显示与时刻表的延误）或 "scheduled"（仅依据时刻表）。

参数：

• stop_id — 6 位数的站点 ID（例如 "060361"）
• line_id — 可选，仅保留一条线路（例如 "2794"）
• limit — 最多返回的到站信息数（默认 10，最多 50）

line_info

查询线路名称、服务的市镇和地区，以及各个方向的信息（终点站名称、首末站、站点数、今日班次、今日首末班车发车时间）。传入线路编号（"4715"）或文本（"Oriente Setubal"）；传入文本时会列出匹配的线路。设置 include_stops=True 后，会添加各方向按顺序排列的站点列表。

service_alerts

查询当前生效的服务通知（默认也包括即将生效的通知）：绕行、施工、罢工、站点不停靠。可按 line_id 和／或 stop_id 筛选。通知大多以葡萄牙语发布。

vehicle_positions

查询当前在线路上运营的公交车实时位置：坐标、行驶方向、速度、终点站名称、所在站点或驶往的站点，以及 GPS 定位数据的时间。

所有时间均为 Europe/Lisbon 时区。工具失败时会返回 {"error": "..."}，而不是抛出异常。

安装

最快方式（需要 uv）：无需克隆，直接从 PyPI 运行。

claude mcp add carris-metropolitana -- uvx carris-metropolitana-mcp

对于 Claude Desktop，使用 "command": "uvx", "args": ["carris-metropolitana-mcp"]。

从源代码安装：

需要 Python 3.10+。

git clone https://github.com/ThiagoJacobLannes/carris-metropolitana-mcp
cd carris-metropolitana-mcp
python -m pip install -e .

在 Windows 上，如果代码存放在云同步文件夹（Google Drive、OneDrive）中，请在该文件夹之外创建虚拟环境：同步客户端会将 desktop.ini 文件放入文件夹，可能导致软件包启动时崩溃。

添加到 Claude Code

claude mcp add carris-metropolitana -- python -m carris_metropolitana_mcp.server

添加到 Claude Desktop

将 claude_desktop_config.snippet.json 合并到 Claude Desktop 的 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "carris-metropolitana": {
      "command": "python",
      "args": ["-m", "carris_metropolitana_mcp.server"]
    }
  }
}

数据来源

所有数据均来自 Carris Metropolitana 官方开放 API：https://api.carrismetropolitana.pt/v2（文档，源代码）。该 API 公开开放，无需密钥，与运营方自有网站和应用使用的是同一 API。Carris Metropolitana 将其作为开放数据发布；其文档未说明具体的数据许可，因此在重新分发数据本身之前，请查看其条款。

大型且变化缓慢的数据列表（全部约 12,000 个站点、约 700 条线路、各地名称和市镇）只下载一次，并在内存中缓存 12 小时；提醒和车辆位置缓存 30 秒。设置 CARRIS_METROPOLITANA_BASE_URL 可指定其他 API 基础 URL。

实时预计信息仅适用于已经投入运营且启用了实时追踪的公交车；其他到站信息来自已发布的时刻表。到站信息仅涵盖当前服务日，因此深夜时列表可能较短。

本项目与 Carris Metropolitana 或 TML 无任何关联，也未获得其认可或与其建立联系。

许可证

MIT