nj-transit-mcp

NJ Transit + PATH + NJ Transit bus MCP 服务端 — v1.3

一个 Model Context Protocol 服务端，为任何兼容 MCP 的 AI （Claude、Gemini CLI、ChatGPT、Cursor、VS Code 等）提供真实的 NJ Transit 和 PATH 时刻表，而不是猜测结果。

为什么 Gemini 以前做不到

面向消费者的 Gemini 应用和网页聊天没有实时交通工具，也不支持 MCP——它根据训练数据和网页摘要作答，因此“实时班次”请求会失败或信息过时。能够调用此服务端的 MCP 客户端可以在查询时从数据源获取答案。

v1 中经过验证的重要区别：

系统	v1 数据	需要密钥？
NJ Transit 铁路 + 轻轨（17 条路线）	来自官方 GTFS rail_data.zip 的计划发车信息	否
NJ Transit 实时延误 / 取消信息	通过 raildata.njtransit.com 获取 GTFS-Realtime TripUpdates + Alerts	是——免费注册（见下文）
PATH（纽瓦克 ↔ 纽约市）	来自 GTFS-Realtime、约每 5 秒更新的实时到站信息	否

每条响应都会标明其 data_source：scheduled、 live_gtfs_rt，或明确的说明。绝不会把仅为计划信息的内容标成“实时”。

关于“地铁”的说明：NJ Transit 没有地铁。类似地铁的服务是本文件中的轻轨线路——Hudson-Bergen（HBLR）、 Newark Light Rail（NLR）、River Line（RVLN）——以及 PATH，也就是 NJ↔纽约市的快速交通系统。两者都包含在 v1 中。

工具（6 个）

• search_stations(query, system="all") — 查找车站 / 站点 ID。 system：nj_transit、nj_bus、path、all。
• next_departures(station, limit=10, system="nj_transit", line?, towards?) — 查询接下来的发车信息。station 可以是名称或站点 ID。名称有歧义时（例如“Secaucus” = Upper Level 或 Lower Level，“PORT AUTHORITY BUS TERMINAL” = 4 个站点 ID），会返回候选项，而不是自行猜测。 公交请使用 system="nj_bus"（v1.3 中仅提供计划信息）。
• trip_between(origin, destination, limit=5, system="nj_transit") — 查询接下来同一班 NJ Transit 列车 / 公交车的信息，包括出发、到达和时长。公交请添加 system="nj_bus"。
• lines(system="all") — 查询所有路线（共 285 条：17 条铁路 + 263 条公交 + 5 条 PATH）。
• service_alerts(system="all") — 设置凭据后查询 NJ 铁路警报；公交和 PATH 警报会报告为不可用，不会凭空编造。
• server_status() — 查询铁路和公交 GTFS 日期范围 / 数量、NJ 实时数据是否已启用，以及 PATH 数据源的更新时间。需要确认答案是实时还是计划信息时，请调用此工具。

已验证测试 — 2026-10-28，约 09:16 ET

使用 python test_client.py（内存中的 FastMCP 客户端）和 8123 端口上的 Streamable HTTP 运行。两种方式均通过，列出了全部 6 个工具。

• server_status：GTFS 日期为 2026 年 9 月 15 日至 2027 年 3 月 13 日，230 个站点、 17 条路线、6,197 个行程；PATH 数据源于 09:16:39 ET 处于实时状态，包含 54 个实体。
• Newark Penn → 下一班：09:17 开往 New York Penn 的 NEC，09:17 开往 Raritan 的 RARV，09:23 开往 New York Penn 的 NEC（计划信息）。
• New York Penn 出站 → 下一班：09:24 开往 Secaucus Upper Level 的 NJCL，09:42 开往 Trenton 的 NEC。
• Newark Penn → New York Penn：09:17 → 09:39（22 分钟，NEC）， 09:23 → 09:41（18 分钟，NEC）。
• PATH 实时信息：Newark → 09:15（现在发车）、09:20 开往 World Trade Center； Hoboken → 09:16 开往 WTC、09:17 开往 33rd St。

运行

cd ~/workspace/mcp-servers/nj-transit
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python server.py            # stdio (default)
.venv/bin/python server.py --transport http --port 8000   # remote

首次运行时会将 GTFS 下载到 data/rail_data.zip，如果文件超过 24 小时则会刷新。 不会记录任何凭据；如果设置了 NJ token，则会将其缓存到 data/.njt_token.json（0600），当天有效，因为 getToken 每天最多调用 10 次（获取 token 后，TripUpdates 本身没有调用次数限制）。

启用 NJ Transit 实时延误（免费，5 分钟）

1. 在 https://developer.njtransit.com/registration 注册 （也列为 https://datasource.njtransit.com）。你会通过电子邮件收到测试和 生产环境凭据。
2. 启动服务前设置这些凭据：

export NJT_USERNAME="your-username"
export NJT_PASSWORD="your-password"
# optional: NJT_BASE_URL=https://raildata.njtransit.com (default)

3. 调用 server_status——nj_live_enabled 应为 true；如果数据源报告了延误， 列车出发信息将包含 data_source: "live_gtfs_rt" 和 delay_min / status。 如果没有这些变量，服务仍可运行，但只提供时刻表信息。

注意：首次运行实时数据时需要验证：GTFS-Realtime 的 trip_id 与 GTFS trip_id 的匹配采用了防御性实现（精确 匹配）；如果 NJ 的 RT 数据源使用不同的行程 ID 方案，实时 出发信息将仍然是时刻表数据，并且 server_status / live_info.live_trips_in_feed 会显示已连接数据源，但未能匹配。 这是 v1 中唯一未经验证的部分，因为没有凭据便无法测试。

连接

Gemini CLI（这是支持 MCP 的 Gemini 接入方式）

~/.gemini/settings.json（或项目中的 .gemini/settings.json）：

{
  "mcpServers": {
    "nj-transit": {
      "command": "/path/to/mcp-servers/nj-transit/.venv/bin/python",
      "args": ["/path/to/mcp-servers/nj-transit/server.py"],
      "env": { "NJT_USERNAME": "", "NJT_PASSWORD": "" },
      "timeout": 30000
    }
  }
}

或者：gemini mcp add --transport stdio nj-transit -- /path/to/.venv/bin/python /path/to/server.py 然后提问：“从 Newark Penn 到 New York Penn 的下一班 NJ Transit 列车是什么？” ——Gemini CLI 将调用 trip_between。

截至此版本，面向消费者的 Gemini 应用（gemini.google.com / 移动应用）不 支持 MCP，因此无法直接将此服务接入该应用。Gemini CLI、Gemini API / ADK（使用 StdioServerParameters 的 MCPToolset）以及第三方 Gemini-API 客户端均可使用。

Claude Desktop / Claude Code / Cursor / VS Code

使用 Stdio，并采用上述相同的命令和参数，在 claude_desktop_config.json 中的 mcpServers 下配置（或在客户端对应的 MCP 设置中配置）。

ChatGPT

ChatGPT 无法使用本地 Stdio 服务。它需要一个支持 Streamable HTTP 的公共 HTTPS URL。此服务现已免费公开，无需身份验证：

• 公共 URL：https://nj-transit-mcp.vercel.app/mcp
• ChatGPT Developer Mode（Pro / Team / Enterprise / Edu）： Settings → Apps & Connectors → Create → 输入 https://nj-transit-mcp.vercel.app/mcp，Authentication：None。

公共部署状态（2026-10-31，17:35 ET）：已上线且免费， 部署在 Vercel 上——已移除 bearer token，生产环境 部署（main，提交 af9e8a6，Public submission pack v1.3） 已重新部署并就绪，且已验证不带 Authorization 标头的 POST /mcp 返回 200 MCP 初始化响应。 源代码：https://github.com/mir-quadri/nj-transit-mcp（公开）。 官方 MCP Registry：io.github.mir-quadri/nj-transit-mcp v1.3.0，状态为 active（于 2026-11-01 发布）。 注意：免费模式下没有 /health 路由——GET / 和 GET /health 返回 404；GET /mcp 返回 405（仅支持 POST）。 速率限制：每个 IP、每个实例每分钟 60 个请求。

NJ Transit 巴士（v1.2，system='nj_bus'）

相同的 6 个工具，仅适用于巴士。数据源：官方公开 GTFS https://www.njtransit.com/bus_data.zip — 263 条线路、16,563 个站点、 33,287 个行程、1,776,403 条 stop_times 记录，服务时间为 2026 年 10 月 20 日至 2027 年 4 月 17 日 （仅使用 calendar_dates，与铁路相同的特殊情况：只有当行程的 service_id 列在该日期的记录中时，该行程才会运行）。使用 system='nj_bus' 调用 search_stations、next_departures、trip_between（添加 system='nj_bus'）和 lines。巴士站点位于街道旁，因此 对于名称不明确的站点（例如“PORT AUTHORITY BUS TERMINAL”对应 4 个站点 ID）， 会返回候选项而不是自行猜测——不确定时请使用站点 ID。

如实说明限制：v1.2 中的巴士出发信息仅为计划时刻。 未启用 BUSDATA 实时延误/警报（这是单独的 API，尚未验证），因此巴士信息绝不会标记为实时。由于 stop_times 有 170 万条记录，服务会在每次查询时逐条流式读取，而不会将其载入内存（绝不会读取 shapes.txt）：巴士出发查询在本地需要约 4–5 秒；冷启动后的首次巴士查询需要约 5 秒来加载元数据。本地验证时间：2026-10-28 约 20:48 ET： Port Authority 站点 3511 → 20:48 巴士 119、190、320；Newark Penn 巴士站点 43283 → 21:28/22:28/23:28 巴士 108，开往 New York；行程 108 Clifton Ave at E 7th Ave → Pavillion Apartments Tower South 21:15 → 21:18。铁路工具保持不变（铁路、巴士和 PATH 合计 17 条线路、285 条线路）。

v1.3 中不包含的内容

• NJ Transit 巴士实时延误/警报：BUSDATA，未启用。
• NYC Subway、SEPTA、Amtrak、渡轮：v1.2 中不包含。server.py 中的提供方 结构专为此类扩展设计；每种交通方式只需新增一个提供方 （GTFS + GTFS-Realtime URL + 站点映射），无需重写。
• 换乘/多段行程：trip_between 仅支持同一趟行程。
• 票价、停车、无障碍信息：所用数据源未提供。

后续步骤（按顺序）

1. 使用外部 ChatGPT 测试公开的 /mcp 端点（最终验证，见上文）。
2. Mir 注册 NJ Transit 开发者凭证 → 端到端验证 NJ 铁路实时延误（上文唯一尚未验证的部分）；如有需要，也可启用巴士 BUSDATA 实时信息。
3. 添加 MTA Subway 作为第 3 个提供方，沿用相同的 6 个工具。

数据来源（已于 2026-10-28 核查）

• NJ Transit GTFS-RT 文档：developer.njtransit.com/doc/NJTRANSIT_Rail_GTFSRT_V1.pdf — getToken / getGTFS / getAlerts / getTripUpdates / getVehiclePositions；每天 10 次令牌调用，RT 调用不限次数。
• NJ Transit 开发者门户：datasource.njtransit.com — BUSDATA、RailData、GTFS-BUS、GTFS-RAIL 目录。
• NJ Transit 公开 GTFS：https://www.njtransit.com/rail_data.zip （Mobility Database 也列出了此数据，2026 年 9 月 15 日至 2027 年 3 月 13 日）。
• NJ Transit 巴士公开 GTFS：https://www.njtransit.com/bus_data.zip （263 条线路、16,563 个站点、2026 年 10 月 20 日至 2027 年 4 月 17 日；已于 2026-10-28 核查）。
• PATH 实时 GTFS-Realtime：https://path.transitdata.nyc/gtfsrt （社区数据源，约每 5 秒刷新一次；站点 ID 已与 PATH 官方 GTFS 静态数据源核对）。