norway-location-transport-mcp

norway-location-transport-mcp

一个 MCP 服务，通过免费的 Entur 和 Kartverket / Geonorge API，为 AI Agent 提供对挪威公共交通和地理空间数据的结构化访问。

这两个数据源可以组合使用：规划行程需要地理编码，查询海拔需要解析地址，行政区查询则可以将坐标关联到地点。一个服务即可回答实用的本地问题，例如：“从这里怎么去卑尔根？”“这条徒步路线沿途的海拔是多少？”“这个地址属于哪个 kommune？”“附近有电动滑板车吗？”

两个数据源均免费，无付费套餐，也无需 API 密钥。Entur 只要求设置一个用于标识客户端的 ET-Client-Name 请求头（见下文）；Kartverket 则无需任何设置。

工具

位置与地理数据（Kartverket）

• search_address(query?, street?, number?, postal_code?, municipality_number?, max_results) — 按自由文本或字段搜索官方地址；支持 * 通配符。返回坐标和地籍编号。
• find_addresses_near(latitude, longitude, radius_m, max_results) — 查找指定点半径范围内的所有地址，并返回距离。
• validate_address(address) — 验证并规范化自由文本地址（模糊匹配）。返回 valid、规范化后的匹配结果和备选项。
• search_place_names(query, max_results) — 搜索官方地名；返回地物类型（Fjell、Innsjø 等）、市镇、郡和坐标。支持 *。
• find_place_names_near(latitude, longitude, radius_m, max_results) — 查找指定点附近最近的命名地物，并返回距离。
• get_elevation(latitude, longitude) — 从国家高程模型（DTM）获取地形海拔。
• get_elevation_profile(path, samples) — 沿路径采样海拔；返回剖面以及总距离、爬升和下降高度。
• transform_coordinates(x, y, from_epsg, to_epsg) — 在坐标参考系之间转换（例如，从 WGS84 4326 转为 UTM33 25833）。
• lookup_admin_unit(latitude?, longitude?, address?) — 查询坐标或地址所属的 kommune 和 fylke，并返回官方代码。
• lookup_property(address?, latitude?, longitude?, max_results) — 通过开放地址登记簿查询地籍（matrikkel）标识符（kommune / gnr / bnr / fnr）。

公共交通（Entur）

• resolve_stop_place(query, max_results) — 将地点或地址解析为 Entur Stop Place ID。
• find_stops_near(latitude, longitude, radius_m, max_results) — 反向地理编码坐标，查找最近的站点。
• plan_trip(from_place?/from_latitude/from_longitude, to_place?/to_latitude/to_longitude, date_time?, arrive_by?, transport_modes?, walk_speed?, num_trip_patterns) — 规划点对点行程；可按交通方式和步行速度筛选。返回包含路段、交通方式、时长和实时班次时间的行程方案。
• get_departures(stop_place_id, count) — 查询站点的后续发车信息，包括实时延误、取消和站台信息。
• get_realtime_status(stop_place_id? | line_id?) — 查询实时状态：针对站点，返回准点、延误和取消的数量；针对线路，返回运行中的车辆和延误信息。
• get_stop_accessibility(stop_place_id) — 返回各站台的轮椅通行情况及摘要。（见下方的无障碍说明。）
• list_quays(stop_place_id) — 列出站点的所有站台，并返回代码和坐标。
• get_fare_zones(stop_place_id) — 查询站点所属的票价（tariff）区域。
• find_shared_vehicles(latitude, longitude, range_m, form_factors?, count) — 搜索所有运营商提供的无固定桩共享车辆（自行车、电动滑板车、汽车和轻便摩托车）。
• find_docking_stations(latitude, longitude, range_m, count) — 查询停靠站，并返回可用车辆和空闲车桩数量。
• get_vehicle_positions(codespace_id?, line_id?, max_results) — 查询车辆实时位置，包括朝向、速度和延误信息。

工具定义位于 src/kartverket.ts 和 src/entur.ts，并在 src/tools.ts 中汇总，由 stdio 和 HTTP 两种入口共用。

设置

npm install
npm run build
npm test

npm test 会通过 stdio 启动服务，并针对实时 API 调用每个工具。

运行

通过 stdio（适用于大多数 MCP 客户端）：

node dist/index.js

通过 Streamable HTTP（适用于基于 HTTP 的客户端）：

node dist/http.js
# listens on http://localhost:3000/mcp  (override with PORT)

Entur 客户端名称要求

Entur 的条款要求每个请求都携带用于标识的 ET-Client-Name 标头，格式类似 company-app。此服务会在每个 Entur 请求中发送该标头。使用 ET_CLIENT_NAME 环境变量设置你自己的值：

ET_CLIENT_NAME="acme-travelbot" node dist/index.js

如果未设置，则使用软件包默认值。Kartverket 不需要标头或密钥。

与 Claude Code 搭配使用

claude mcp add norway -- node C:\Users\trond\norway-location-transport-mcp\dist\index.js

然后可以这样提问：“规划一段从 Oslo S 到 Bergen 的行程，并告诉我 Galdhøpiggen 的海拔。”

远程版本（Cloudflare Workers）

worker/ 包含一个远程部署版本：通过 MCP Streamable HTTP 提供相同的 21 个工具，因此可以将此服务添加为 claude.ai 连接器。它与本地服务共享工具定义（src/tools.ts 将 z 作为参数，因此同时兼容本地 MCP SDK v1 / zod 3 和 worker 的 SDK v2 / zod 4）。

cd worker
npm install
npm run dev     # local test at http://127.0.0.1:8787/mcp
node test-http.mjs

部署（需要 Cloudflare 帐户和 wrangler login）：

cd worker
npm run deploy

将 Entur 客户端名称设置为 worker 变量：

cd worker
npx wrangler secret put ET_CLIENT_NAME

部署后，将包含你的 workers.dev URL 的 remotes 条目添加到 server.json。

调用示例

获取 Oslo S 的下一班车次：

{ "name": "get_departures", "arguments": { "stop_place_id": "NSR:StopPlace:59872", "count": 5 } }

规划仅乘坐公交车／有轨电车且设置步行速度的行程：

{ "name": "plan_trip", "arguments": {
  "from_place": "NSR:StopPlace:59872",
  "to_latitude": 59.95, "to_longitude": 10.78,
  "transport_modes": ["bus", "tram"], "walk_speed": 1.4
} }

短路径的海拔剖面：

{ "name": "get_elevation_profile", "arguments": {
  "path": [{ "latitude": 61.636, "longitude": 8.312 }, { "latitude": 61.64, "longitude": 8.32 }],
  "samples": 20
} }

将 WGS84 坐标转换为 UTM33：

{ "name": "transform_coordinates", "arguments": { "x": 10.7461, "y": 59.9127, "from_epsg": 4326, "to_epsg": 25833 } }

说明和限制

• 坐标：所有坐标均为 WGS84 纬度／经度。Kartverket API 使用 EPSG 4326 查询，因此数值一致；在挪威，EUREF89（4258）与其相差不到一米。
• 无障碍功能：Entur 的免费 JourneyPlanner 会提供每个站台的轮椅通行信息。更详细的设施信息（电梯、触觉引导）仅存在于 Entur 经过身份验证的 Stop Register API 中，此处无法获取；该工具会说明这一点。
• 速率限制：任何一个数据源触发速率限制时，都会返回清晰的错误，提示 Agent 重试。
• 署名：Kartverket / Geonorge 和 Entur 的数据采用 NLOD 许可。展示数据时请注明来源。

工作原理

• src/index.ts 通过 stdio 使用 MCP（通过 stdin/stdout 传输 JSON-RPC）。src/http.ts 通过 Streamable HTTP 使用 MCP，并管理会话。两者都通过 src/server.ts 构建同一个服务。
• 每个工具都声明了一个 Zod 输入架构，其中的说明会由大模型直接读取；调用工具无需外部文档。
• 结果是经过精简的 JSON 文本，仅包含 Agent 所需内容，而非上游原始负载。
• 切勿使用 console.log 写入 stdout，否则会破坏 stdio 协议。请将日志写入 stderr。

许可证

MIT © Trond Bjørøy。数据 © Kartverket 和 Entur，采用 NLOD 许可。