norway-location-transport-mcp

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

这两个数据源相互补充：行程规划需要地理编码，海拔需要地址解析，行政区划查询将坐标与地点关联起来。一个服务器即可回答实用的本地问题——"我如何从这里去卑尔根？"、"这条徒步路线的海拔是多少？"、"这个地址属于哪个市镇？"、"附近有电动滑板车吗？"。

两个数据源均免费，无付费层级，无需 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?) — 坐标或地址属于哪个市镇和郡，附带官方代码。

• lookup_property(address?, latitude?, longitude?, max_results) — 通过开放地址注册表获取地籍（matrikkel）标识符（kommune / gnr / bnr / fnr）。

公共交通（Entur）

• resolve_stop_place(query, max_results) — 将地点或地址解析为 Entur 站点 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 到卑尔根的行程，并告诉我 Galdhøpiggen 的海拔。"

远程版本（Cloudflare Workers）

worker/ 目录包含远程部署：相同的 21 个工具通过 MCP Streamable HTTP 提供服务，因此该服务器可以作为 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

部署后，将 remotes 条目（使用您的 workers.dev URL）添加到 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 的认证站点注册 API 中，此处不可用；工具会明确说明。

• 任一来源的速率限制都会以清晰的错误提示返回，要求代理重试。

• 归属：来自 Kartverket / Geonorge 和 Entur 的数据遵循 NLOD 许可。展示数据时请注明来源。

工作原理

• src/index.ts 通过 stdio 使用 MCP 协议（stdin/stdout 上的 JSON-RPC）。src/http.ts 通过 Streamable HTTP 使用 MCP 协议，并包含会话管理。两者通过 src/server.ts 构建相同的服务器。

• 每个工具都声明一个 Zod 输入模式，并附带 LLM 可直接读取的描述——调用工具无需外部文档。

• 结果被裁剪为代理所需的 JSON 文本，而非原始上游负载。

• 切勿使用 console.log 写入 stdout；这会破坏 stdio 协议。请将日志写入 stderr。

许可证

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