transitland-mcp-server

---

概述

通过 Transitland 获取全球数千家运营方的公共交通数据。Transitland 是一个开放的 GTFS、GTFS-Realtime 和 GBFS 数据源聚合平台。可查找运营方及其数据源，也可查询线路、站点和实时出发信息。

工具

工具	描述
transitland_find_operators	按名称、坐标/半径、边界框、国家/地区或 Onestop ID 查找公共交通运营方/机构
transitland_get_operator	按 Onestop ID 获取完整的运营方记录，包括机构、数据源和来源标签
transitland_find_feeds	查找 GTFS、GTFS-Realtime 和 GBFS 数据源，包括获取 URL、许可条款和数据新鲜度
transitland_find_routes	按坐标/半径、边界框、运营方、Onestop ID 或 GTFS 模式查找线路
transitland_find_stops	按名称、坐标/半径、边界框、Onestop ID 或运营方网络查找站点/车站
transitland_get_departures	获取某站点的出发信息，并为每条记录标记 realtime true/false

Transitland 不会对地名进行地理编码——在调用按地理位置筛选的工具前，请先使用地理编码 MCP 服务将地点解析为坐标（例如，使用 openstreetmap-mcp-server 的 openstreetmap_geocode）。

资源

资源	描述
transitland://operator/{onestop_id}	按 Onestop ID 查询运营方记录——机构、服务地点、已发布的数据源和来源标签
transitland://feed/{onestop_id}	按 Onestop ID 查询数据源记录——规范、获取 URL、许可条款和新鲜度

也可以通过工具（transitland_get_operator、transitland_find_feeds）访问所有资源数据。

功能参考

页面默认限制为 20 条，最多为 100 条。超出限制的 limit 会被截断，并显示提示；页面达到限制时会返回 truncated、shown 和 cap。使用返回的 after 游标继续查询。

transitland_find_operators _工具

• 可按 search（名称）、lat+lon+radius（最大 100,000 米，默认 1,000 米）、bbox、onestop_id 或 adm0_name/adm1_name（国家/地区）筛选——至少需要一项，否则调用会因 no_filter 失败
• lat 和 lon 必须同时提供，否则调用会因 incomplete_point 失败
• 返回每个运营方的 Onestop ID、名称、服务地点、已发布的数据源（GTFS_RT 条目表示可能提供实时出发信息）和 Wikidata QID

---

transitland_get_operator _工具

• 接受 Onestop ID（例如 o-9q9-bart）或内部整数 ID
• 返回机构（每个机构均附有服务地点）、已发布的数据源和来源标签：Wikidata QID、美国 NTD ID、通用 Twitter/X 用户名
• 如果无法解析该 ID，则返回 operator_not_found

---

transitland_find_feeds _工具

• 可按 operator_onestop_id（来自 transitland_find_operators）、spec（gtfs/gtfs-rt/gbfs/mds；大小写及下划线/连字符形式（如 GTFS_RT）均可接受）、search 或 fetch_error 筛选——至少需要一项
• 每个数据源都会返回其获取 URL、实时端点、新鲜度（上次获取时间、内容哈希、涵盖的日历时间范围）和许可条款——再分发、商业用途、衍生产品和署名的状态为 yes/no/unknown，绝不会根据空白字段推断——以及已知的 SPDX 标识符和署名文本
• authorizationRequired 标记下载时需要单独密钥或注册的数据源

---

transitland_find_routes _工具

• 可按 lat+lon+radius（最大 50,000 米，默认 1,000 米）、bbox、operator_onestop_id、onestop_id、route_type（GTFS 模式整数）或 search 筛选——至少需要一项
• lat 和 lon 必须同时提供，否则调用会因 incomplete_point 失败
• 返回短名称/长名称、GTFS 模式（公交、地铁、铁路、渡轮、有轨电车等）、品牌颜色，以及运营机构和来源数据源的 Onestop ID。路线类型缺失时为 null，模式为 unknown
• 返回的是计划时刻表（GTFS 静态）中的路线定义，而非实时车辆位置

---

transitland_find_stops _工具

• 可按 lat+lon+radius（最大 10,000 米，默认 500 米）、bbox、onestop_id、served_by_onestop_ids（逗号分隔的运营方/路线 Onestop ID）或站点名称 search 筛选——至少需要一项。名称搜索无需地理编码
• 返回坐标（上游缺失时为 null）、带标签的 location_type（站点、车站、入口、节点、登乘区）、轮椅无障碍信息、时区，以及子站台对应的父车站 Onestop ID
• 出发信息关联到站台级站点（location_type 为 0）——车站可能没有出发信息，因此请使用其子站台

transitland_get_departures _工具

• 先用 transitland_find_stops 将站点解析为其 Onestop ID；若无法解析，则返回 stop_not_found。next_seconds 用于设置前瞻时间窗口：60–86,400（默认值为 3,600）——如果站点未返回结果，请扩大窗口或设置 use_service_window: true
• 每个出发信息都包含 realtime 标志（实时 GTFS-Realtime 预测为 true，计划时间为 false）和 scheduleRelationship（STATIC、SCHEDULED、ADDED、CANCELED、UNSCHEDULED、DUPLICATED）
• 还会返回计划和预计时间（含秒数延误）、线路、终点标识、模式、行程、方向和无障碍信息；顶层的 realtimeAvailable 用于报告该站点的源是否发布 GTFS-RT

---

transitland://operator/{onestop_id} _资源

• 与 transitland_get_operator 返回的信息一致——包括机构、服务区域、已发布的源和来源标签
• onestop_id 接受 Onestop ID（例如 o-9q9-bart）或内部整数 ID；若无法解析，则返回 operator_not_found

---

transitland://feed/{onestop_id} _资源

• 与 transitland_find_feeds 返回的单个源结果一致——包括规范、获取 URL、实时端点、许可条款和最新状态
• onestop_id 接受源 Onestop ID（例如 f-9q9-bart）或内部整数 ID；若无法解析，则返回 feed_not_found
• 空白许可字段将返回 unknown/null，绝不会推断为宽松许可

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录及可选的 OpenTelemetry 跟踪。

Transitland 专属功能：

• 为 Transitland v2 REST API 提供直接 HTTP 客户端——无需 SDK 依赖，通过少量 GET 端点使用扁平的查询参数契约
• Onestop ID（o-/f-/r-/s-）是标识符主干——每个结果都会显示该 ID；输入时除内部整数 ID 外，也可接受 Onestop ID
• 源查询仅返回最新源版本的最新状态，不提供完整的获取历史记录
• 不提供覆盖范围多边形和线路/站点几何信息；结果改为包含精简的国家/地区/城市位置摘要

便于 Agent 使用的输出：

• 明确标示实时状态：每个出发信息均包含 realtime 和 scheduleRelationship，顶层还包含 realtimeAvailable
• 空白许可字段将返回 unknown/null，绝不会推断为宽松许可，并会提示 Agent 在重新分发前通过许可 URL 确认
• 上游分页 URL 中包含 API 密钥；输出中仅显示不透明的 after 游标，因此密钥不会出现在工具输出或日志中
• 无结果时会返回可执行的提示（先进行地理编码、扩大时间窗口、尝试子站台），而非错误

开始使用

将以下内容添加到 MCP 客户端配置文件中。需要 Transitland API 密钥——获取方式请参阅先决条件。

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "TRANSITLAND_API_KEY=your-api-key",
        "ghcr.io/cyanheads/transitland-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TRANSITLAND_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• Transitland v2 API 密钥——请在 Transitland 开发者门户注册。免费套餐有速率限制；Pro 套餐可提高配额。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/transitland-mcp-server.git

2. 进入目录：

cd transitland-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set TRANSITLAND_API_KEY

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 架构进行验证。缺少 TRANSITLAND_API_KEY 会导致启动失败，并显示包含该变量名的提示横幅，而不是等到首次调用工具时才失败。

变量	说明	默认值
TRANSITLAND_API_KEY	必填。 Transitland v2 API 密钥，通过 apikey 查询参数发送。	—
TRANSITLAND_BASE_URL	Transitland REST API 基础 URL。可覆盖此值以固定使用特定部署或可自托管的实例。	https://transit.land/api/v2/rest
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	挂载 MCP 服务的 HTTP 端点路径。	/mcp
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果，并按键名进行脱敏（自由格式值中的机密仍会保留）。大小上限由 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 决定（默认值为 16384）。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩（追踪记录、指标、完成日志）。	false

可选覆盖项的完整列表请参见 .env.example。

HTTP 会话默认无状态；设置 MCP_SESSION_MODE 可覆盖此行为。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t transitland-mcp-server .
docker run --rm -e TRANSITLAND_API_KEY=your-key -p 3010:3010 transitland-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/transitland-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化 Transitland 服务。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖运营商、数据源、路线、站点和发车信息，共六个工具。
src/mcp-server/resources	资源定义（*.resource.ts）。运营商和数据源记录。
src/services/transitland	Transitland v2 REST 客户端——处理 HTTP、注入 apikey、游标规范化、错误分类，以及各端点的类型化方法。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 CLAUDE.md / AGENTS.md。简要说明如下：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总入口注册新工具和资源
• 封装 Transitland API：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段（尤其是许可条款——空白表示 unknown，而非不受限制）

数据与许可

公交数据由 Transitland 提供，这是一个开放注册平台，汇集了全球数千家运营商的 GTFS、GTFS-Realtime 和 GBFS 数据源。基于 Transitland 数据构建的产品必须显示名称“Transitland”，并附上指向 transit.land/terms 的链接，确保最终用户能够清楚看到。

Transitland 汇集了数千家运营商的数据源，每家运营商都可能有自己的许可和署名要求。请在重新分发或发布通过此服务获取的数据之前，查看 transit.land/terms 中各数据源的许可条款，并遵守每个源数据的要求。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。