bikerouter-mcp

bikerouter.de로 자전거 경로를 계획하는 MCP 서버입니다. BRouter 엔진(Arndt Brenschede 제작) 위에서 동작하는 BRouter-Web 프런트엔드(Norbert Renner 제작)이며, OpenStreetMap 데이터를 기반으로 라우팅합니다.

아무 MCP 클라이언트(Claude Code, Claude Desktop 등)에 연결하고 "라인강을 따라 쾰른에서 본까지 자갈길 경로를 계획하고 GPX를 줘" 같은 요청을 하면 됩니다.

할 수 있는 일

plan_route 출력 예시:

**Route** (profile: `trekking`)
Alexanderplatz, Berlin → Brandenburger Tor, Berlin

- Distance: **5.2 km**
- Estimated riding time: **20 min** (⌀ 15.6 km/h, from the profile's physics model)
- Ascent: **80 m** / descent: **60 m**
- Elevation: 35–55 m (start 35 m, end 55 m)

- Surfaces: asphalt 76.9% (4 km), gravel 23.1% (1.2 km)
- Way types: cycleway 38.5% (2 km), residential 38.5% (2 km), track 23.1% (1.2 km)

Open in bikerouter.de: https://bikerouter.de/#map=14/52.518154/13.396327/standard&lonlats=…&profile=trekking

Related MCP server: Hiking MCP Server

설치

cd bikerouter-mcp
npm install     # also builds via the prepare script
npm test

Claude Code에 등록:

claude mcp add bikerouter -- node /absolute/path/to/bikerouter-mcp/dist/index.js

또는 claude_desktop_config.json / 다른 MCP 클라이언트에 추가:

{
  "mcpServers": {
    "bikerouter": {
      "command": "node",
      "args": ["/absolute/path/to/bikerouter-mcp/dist/index.js"]
    }
  }
}

API 키는 필요 없습니다. 서비스는 무료이며 인증이 필요 없습니다.

구성

모두 선택 사항이며 환경 변수로 설정합니다:

BRouter API에 매핑되는 방식

요청은 BRouter의 ServerHandler.java에 문서화된 대로 일반 GET /brouter 호출입니다:

/brouter?lonlats=lon,lat|lon,lat&nogos=lon,lat,radius,weight|…&profile=trekking
        &alternativeidx=0&format=geojson&timode=1&straight=0&profile:avoid_unsafe=true

• waypoints → lonlats (장소 이름은 먼저 지오코딩되며 이전 경유지 쪽으로 치우칩니다)

• avoid_areas → nogos (하드 노고(no-go)로 설정하려면 weight를 생략)

• straight_from → straight (직선 구간)

• profile_options → profile:NAME=VALUE

• alternative_index → alternativeidx (대체 경로의 경우 1–3)

• turn_instructions → timode (GeoJSON 응답의 음성 안내)

GeoJSON 응답은 로컬에서 요약됩니다. 트랙 길이, filtered ascend, total-time, total-energy는 트랙 속성에서 가져오고, 하강 고도는 필터링된 상승 고도와 순 높이 변화에서 파생되며, 노면/도로 종류/매끄러움 분석은 messages 테이블(WayTags를 Distance로 가중치)에서 집계됩니다.

알아두면 좋은 제한 사항

• 라우팅 품질은 OpenStreetMap 품질을 따릅니다. 노면 또는 접근 태그가 누락되면 이상한 우회로가 생성될 수 있으므로, 주행 전에 반환된 지도 링크에서 항상 경로를 확인하세요.

• BRouter에는 도로명이 없으므로 회전 안내에 도로 이름 없이 "1.2km 앞에서 우회전"이라고만 표시됩니다. 이는 이 서버가 아닌 엔진의 속성입니다.

• 예상 주행 시간은 프로필의 물리 모델(라이더 질량, 출력, 항력)에서 비롯됩니다. 현실적인 수치를 얻으려면 profile_options로 totalMass, bikerPower, maxSpeed를 재정의하세요.

• 고도는 SRTM 적용 범위가 필요합니다. 대략 북위/남위 60° 이상에서는 고도 없이 트랙이 반환되며 요약에 그렇게 표시됩니다.

• 공용 서비스는 무료 커뮤니티 운영 인스턴스이므로 요청량을 적정하게 유지하거나 자체 BRouter 서버를 실행하고 BIKEROUTER_HOST를 설정하세요.

• 프로필은 서버마다 다릅니다. list_profiles는 기본 BRouter/BRouter-Web 프로필 카탈로그를 제공하며, 특정 호스트가 실제로 제공하는 프로필을 확인하려면 verify: true를 전달하세요.

테스트

npm test는 서버를 빌드하고 node --test를 실행합니다:

• URL 구성, 경유지 검증, .brf 매개변수 구문 분석 및 GeoJSON 요약기에 대한 단위 테스트

• 스텁 BRouter 호스트에 대해 실제 서버 바이너리와 MCP over stdio로 통신하는 엔드투엔드 테스트로, 라우팅, GPX 내보내기, 프로필 나열 및 BRouter의 일반 텍스트 오류 응답을 다룹니다.

테스트는 공용 서비스를 전혀 건드리지 않으므로 오프라인에서 실행됩니다.

크레딧 및 라이선스

서버 코드: MIT. 이 서버는 클라이언트일 뿐이며 라우팅은 BRouter(MIT)를 통해 BRouter-Web / bikerouter.de에서 수행되며, 지도 데이터는 © OpenStreetMap 기여자(ODbL)입니다.