norway-location-transport-mcp

AI 에이전트가 무료 Entur 및 Kartverket / Geonorge API를 통해 노르웨이 대중교통 및 지리공간 데이터에 구조적으로 접근할 수 있게 해주는 MCP 서버입니다.

두 소스는 서로 보완합니다. 여행 계획에는 지오코딩이 필요하고, 고도에는 주소 해석이 필요하며, 행정 구역 조회는 좌표를 장소에 연결합니다. 하나의 서버가 실용적인 지역 질문에 답합니다 — "여기서 베르겐까지 어떻게 가나요?", "이 하이킹 경로의 고도는 얼마인가요?", "이 주소는 어느 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) — 정류장이 속한 요금 구역을 반환합니다.

• 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의 이용 약관은 모든 요청에 company-app 형식의 식별용 ET-Client-Name 헤더를 포함하도록 요구합니다. 이 서버는 모든 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

그런 다음 예를 들어 "오슬로 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

배포 후 server.json에 workers.dev URL이 포함된 remotes 항목을 추가하세요.

예시 호출

오슬로 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)는 노르웨이에서 1미터 미만의 차이를 보입니다.

• 접근성: Entur의 무료 JourneyPlanner는 승강장별 휠체어 접근성을 제공합니다. 더 상세한 장비 정보(엘리베이터, 점자 유도)는 Entur의 인증된 Stop Register API에만 있으며 여기서는 사용할 수 없습니다. 도구가 이를 명시합니다.

• 속도 제한: 두 소스 중 하나에서 발생한 속도 제한은 에이전트에게 재시도를 요청하는 명확한 오류로 표시됩니다.

• 출처 표시: Kartverket / Geonorge 및 Entur의 데이터는 NLOD에 따라 제공됩니다. 데이터를 표시할 때 출처를 명시하세요.

작동 방식

• src/index.ts는 stdio를 통해 MCP를 사용합니다(stdin/stdout의 JSON-RPC). src/http.ts는 세션 관리를 통해 Streamable HTTP로 MCP를 사용합니다. 둘 다 src/server.ts를 통해 동일한 서버를 구축합니다.

• 각 도구는 LLM이 직접 읽는 설명이 포함된 Zod 입력 스키마를 선언합니다. 도구를 호출하는 데 외부 문서가 필요 없습니다.

• 결과는 원시 업스트림 페이로드가 아니라 에이전트가 필요로 하는 만큼만 정리된 JSON 텍스트입니다.

• console.log로 stdout에 쓰지 마세요. stdio 프로토콜을 손상시킵니다. stderr로 로그를 남기세요.

라이선스

MIT © Trond Bjørøy. 데이터 © Kartverket 및 Entur, NLOD에 따름.