osm-mcp

OpenStreetMap을 위한 MCP 서버입니다: 지오코딩, 도보/자동차/자전거 거리 및 소요 시간, 다중 경유지 경로 최적화, 등시선 및 POI 검색 — AI 어시스턴트와 함께 여행 계획을 위해 설계되었습니다.

11개의 도구, 모두 읽기 전용입니다. 모든 백엔드는 무료 공개 OpenStreetMap 서비스입니다. API 키가 필요하지 않습니다. OpenRouteService 키를 선택적으로 제공하여 라우팅 엔진을 전환할 수 있습니다.

📖 전체 문서: https://osm-mcp.ni-c.de

또 다른 OSM MCP 서버인 이유는?

• 올바른 도보/자전거 경로. 공개 OSRM 데모 서버는 OSRM URL 경로 내의 프로필 세그먼트를 무시하고 FOSSGIS routed-foot / routed-bike / routed-car 경로 접두사를 사용하지 않으면 항상 자동차 경로를 반환합니다. 대부분의 기존 OSM MCP 서버는 이를 잘못 처리하여 도보 쿼리에 대해 자동차 주행 시간을 조용히 반환합니다. 이 서버는 접두사를 사용하며, 라이브 스모크 테스트에서 도보 경로가 자동차 경로보다 훨씬 느리다는 것을 확인합니다.

• 정책을 준수하도록 설계됨. 서비스별 속도 제한(Nominatim 및 OSRM: 초당 1개 요청), 모든 요청에 식별 가능한 User-Agent(Nominatim 사용 정책 필수), 응답 캐싱, Overpass 동시성 제한(2개 슬롯) 및 429/5xx 발생 시 Overpass 미러로 자동 장애 조치.

• Photon 지원. komoot의 Photon을 통한 선택적 오타 허용 지오코딩. 대화형 사용에 적합하며, Nominatim을 반복적으로 호출하는 것보다 LLM 기반 조회에 더 적합합니다.

Related MCP server: Geo MCP Worker

요구 사항

• Node.js ≥ 22

• 공개 OpenStreetMap 서비스에 대한 인터넷 접속(아래 표 참조)

설정

모든 변수는 선택 사항입니다 — 서버는 기본 설정으로 작동합니다.

설치

claude mcp add osm -- npx -y osm-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "osm": {
      "command": "npx",
      "args": ["-y", "osm-mcp"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.osm]
command = "npx"
args = ["-y", "osm-mcp"]

컨테이너(멀티 아키텍처, SBOM 및 빌드 출처 포함):

docker run -i --rm ghcr.io/ni-c/osm-mcp

-i는 필수입니다 — 프로토콜은 stdin과 stdout을 통해 실행됩니다. 게시할 포트는 없습니다. 더 많은 클라이언트 설정 방법은 클라이언트 가이드에 있습니다.

도구

모든 장소 입력은 이름/주소(자동 지오코딩) 또는 리터럴 좌표 "lat,lon"을 허용합니다.

사용 정책 및 저작자 표시

이 서버는 공유 커뮤니티 인프라와 통신합니다. 클라이언트 측에서 공개된 제한을 적용하지만, 운영자는 사용자에게 전체 사용량을 가볍고 비상업적으로 유지할 것을 요청합니다:

• 데이터: © OpenStreetMap 기여자, ODbL 1.0에 따라 라이선스 부여.

• Nominatim: 최대 초당 1개 요청, 식별 가능한 User-Agent 필수, 결과 캐싱 (정책).

• OSRM / Valhalla (FOSSGIS): 합리적인 비상업적 사용; 최대 초당 1개 요청 (정보).

• Overpass: IP당 약 2개 동시 슬롯, 하루 10,000개 미만 쿼리 (위키).

• Photon: 공정 사용 (photon.komoot.io).

대량 사용 또는 상업적 사용의 경우 서비스를 자체 호스팅하고 *_BASE_URL 변수를 자체 인스턴스로 지정하세요.

안전

• 모든 도구는 읽기 전용입니다. 서버는 OpenStreetMap에 절대 쓰지 않습니다.

• 자격 증명이 필요하지 않습니다. 선택적 ORS_API_KEY는 로드 후 프로세스 환경에서 제거되고 오류 메시지에서 가려집니다.

• OSM에서 가져온 콘텐츠(이름, 주소, 태그)는 도구 결과에서 신뢰할 수 없는 데이터로 표시되어 모델이 이를 데이터로 취급하고 명령으로 취급하지 않도록 합니다.

• 업스트림 오류 본문은 잘리고 HTML 오류 페이지는 모델 컨텍스트에 도달하기 전에 삭제됩니다.

• 리디렉션은 절대 따르지 않습니다. 모든 요청은 시간 초과됩니다.

개발

npm install
npm run lint          # eslint + prettier
npm test              # unit tests (all upstream APIs mocked)
npm run test:coverage
npm run build
npm run smoke         # opt-in LIVE test against the real public services

릴리스

태그 기반, 수동 게시 단계 없음:

1. CHANGELOG.md에서 [Unreleased] 항목을 새 ## [x.y.z] - YYYY-MM-DD 섹션으로 이동하고 package.json 버전을 올립니다.

2. npm run lint && npm run build && npm run test:coverage.

3. 커밋 후 서명된 주석 태그: git tag -s vx.y.z -m "vx.y.z".

4. git push origin main vx.y.z.

그러면 release.yml이 테스트를 실행하고, Trusted Publishing을 통해 npm에 출처와 함께 게시하며(토큰 비밀 불필요), CHANGELOG 섹션에서 GitHub 릴리스를 생성하고, MCP 레지스트리에 io.github.ni-c/osm-mcp로 게시합니다. ci.yml은 동일한 태그에서 멀티 아키텍처 이미지를 GHCR에 푸시합니다.

레지스트리 단계가 실패하면 main에서 수정하고 Publish to MCP Registry 워크플로를 실행하세요 — 태그 작업을 다시 실행하지 마십시오. 그러면 이전 트리를 체크아웃하게 됩니다.

라이선스

MIT