Molayo

© 2026 Molayo

GitHub요약2026. 06. 10. 21:24

tomtom-international/tomtom-maps-mcp

요약

TomTom Maps MCP Server는 검색, 경로 안내, 교통 정보 등 TomTom의 지리공간 데이터를 AI 워크플로우에 통합할 수 있게 해주는 도구입니다. MCP 프로토콜을 통해 Claude Desktop 등 AI 클라이언트에서 정밀한 위치 데이터를 쉽게 활용할 수 있습니다.

핵심 포인트

  • TomTom의 위치 서비스를 AI 에이전트와 연동 가능
  • MCP 프로토콜을 통한 간편한 지리공간 데이터 통합
  • 원격 서버 연결로 Node.js나 Docker 설치 없이 즉시 사용 가능
  • Claude Desktop 및 VS Code 환경 지원

TomTom Maps MCP Server는 검색, 경로 안내 (Routing), 교통 정보 및 정적 지도 (Static Maps) 데이터를 포함한 TomTom의 위치 서비스에 대한 원활한 액세스를 제공함으로써 지리공간 (Geospatial) 개발을 간소화합니다. 이를 통해 정밀하고 정확한 지리 위치 (Geolocation) 데이터를 AI 워크플로우 및 개발 환경에 쉽게 통합할 수 있습니다.

  • 데모 (Demo)
  • 보안 공지 (Security Notice)
  • 원격 MCP 서버 (Remote MCP Server) (설치 불필요)
  • 빠른 시작 (Quick Start)
  • 통합 가이드 (Integration Guides)
  • 사용 가능한 도구 (Available Tools)
  • 디버그 UI (Debug UI)
  • 로컬 개발 (Local Development)
  • 문제 해결 (Troubleshooting)
  • 기여 및 피드백 (Contributing & Feedback)
  • 보안 (Security)
  • 라이선스 (License)

Public Preview— TomTom Maps 원격 MCP 서버는 현재 퍼블릭 프리뷰 (Public Preview) 단계입니다.

가장 쉬운 시작 방법은 TomTom에서 호스팅하는 MCP 서버에 직접 연결하는 것입니다. Node.js, Docker 또는 로컬 설정이 필요하지 않습니다.

엔드포인트 (Endpoint):

전제 조건 (Prerequisites):

  • MCP 서버 액세스가 활성화된 유효한 TomTom API 키 (API 키 관리 참조)

MCP 클라이언트 설정에 다음을 추가하세요:

{
"mcpServers": {
"tomtom-mcp": {
...

백엔드를 선택하려면 선택 사항인 tomtom-maps-backend 헤더를 추가하세요:

TomTom Maps (기본값):

{
"mcpServers": {
"tomtom-mcp": {
...

TomTom Orbis Maps:

{
"mcpServers": {
"tomtom-mcp": {
...

tomtom-maps-backend 헤더가 생략되면 서버는 기본적으로 TomTom Maps를 사용합니다.

워크스페이스에서 .vscode/mcp.json을 생성하거나 편집하세요:

{
"servers": {
"tomtom-mcp": {
...

가장 빠른 옵션은 사전 빌드된 확장 프로그램을 설치하는 것입니다. 자세한 내용은 Claude Desktop 설정 가이드를 참조하세요.

또는 구성 파일을 편집하여 Claude Desktop이 원격 서버를 직접 사용하도록 구성할 수 있습니다:

macOS:~/Library/Application Support/Claude/claude_desktop_config.json

Windows:%APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"tomtom-mcp": {
...

참고: MCP 클라이언트가 사용자 정의 헤더를 포함한 원격 HTTP 연결을 지원하지 않는 경우, 대신 로컬 설정을 사용하세요.

TomTom Maps MCP Server의 로컬 배포 버전을 최신 상태로 유지하는 것은 MCP 클라이언트/운영자의 책임입니다. TomTom은 알려진 취약점(vulnerabilities)을 해결하기 위해 업데이트를 게시하지만, 로컬 인스턴스에 업데이트, 패치 또는 권장되는 보안 설정을 적용하지 않으면 알려진 취약점에 노출될 수 있습니다.

  • Node.js 22.x
  • TomTom API key

TomTom API key를 얻는 방법:

  • TomTom Developer Portal에서 개발자 계정을 생성하고 로그인합니다.
  • 왼쪽 메뉴에서 API & SDK Keys로 이동합니다.
  • red Create Key 버튼을 클릭합니다.
  • 전체 액세스를 보장하기 위해 사용 가능한 모든 API를 선택하고, 키에 이름을 지정한 후 Create를 클릭합니다.

더 자세한 내용은 TomTom API Key Management Documentation을 방문하세요.

npm install @tomtom-org/tomtom-mcp@latest
# 또는 설치 없이 직접 실행
npx @tomtom-org/tomtom-mcp@latest

다음 방법 중 하나를 사용하여 TomTom API key를 설정하세요:

# 옵션 1: .env 파일 사용 (권장)
echo "TOMTOM_API_KEY=your_api_key" > .env
# 옵션 2: 환경 변수 (Environment variable)
...
변수 (Variable)설명 (Description)기본값 (Default)
TOMTOM_API_KEY귀하의 TomTom API key-
MAPS사용할 백엔드 (Backend): tomtom-maps (TomTom Maps) 또는 tomtom-orbis-maps (TomTom Orbis Maps)tomtom-maps
PORTHTTP 서버를 위한 포트 (Port)3000
LOG_LEVEL로깅 레벨 (Logging level): debug, info, warn, 또는 error. 모든 로그를 확인하려면 로컬 개발 시 debug를 사용하세요info

Stdio 모드 (기본값 - Claude와 같은 AI 어시스턴트용):

# stdio를 통해 MCP 서버 시작
npx @tomtom-org/tomtom-mcp@latest

HTTP 모드 (웹 애플리케이션 및 API 통합용):

npm run build # 먼저 빌드해야 합니다 (필수)
npm run start:http
# 또는 빌드된 바이너리를 직접 실행
...

HTTP 모드로 실행할 때는 tomtom-api-key 헤더에 API key를 포함해야 합니다. 또한 tomtom-maps-backend 헤더를 사용하여 요청마다 선택적으로 맵 백엔드를 설정할 수 있습니다:

tomtom-api-key: <API_KEY>
tomtom-maps-backend: tomtom-maps # 또는 tomtom-orbis-maps

참고: tomtom-maps-backend 헤더는 MAPS 환경 변수 (env var) 없이 서버를 시작할 때(이중 백엔드 모드, dual-backend mode)만 사용됩니다. 시작 시 MAPS가 설정되어 있다면, 해당 헤더는 무시되며 서버는 고정된 백엔드를 사용합니다.

예를 들어, curl을 사용하여 요청을 보내는 방법은 다음과 같습니다:

curl --location 'http://localhost:3000/mcp' \
--header 'Accept: application/json,text/event-stream' \
--header 'tomtom-api-key: <API KEY>' \
...

Docker 설정 또한 동일한 인증 방식을 사용하는 이 HTTP 모드를 사용하도록 구성되어 있습니다.

Docker 모드 (권장):

# 옵션 1: docker run 직접 사용
# 참고: TomTom Maps가 기본 백엔드입니다 (npm 패키지와 동일)
docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-maps-mcp:latest
...

두 가지 Docker 옵션 모두 서버를 HTTP 모드로 실행합니다. 위의 HTTP 모드 curl 예시와 같이 tomtom-api-key 헤더를 통해 API 키를 전달하세요.

TomTom Maps MCP 서버는 다양한 AI 개발 환경 및 도구에 쉽게 통합될 수 있습니다.

다음 가이드들은 MCP 서버를 사용자의 도구 및 환경에 통합하는 데 도움을 줍니다:

  • Claude Desktop 설정 - TomTom Maps MCP 서버와 함께 작동하도록 Claude Desktop을 구성하는 방법
  • VS Code 설정 - Visual Studio Code에서 개발 환경을 설정하는 방법
  • Cursor AI 통합 - TomTom Maps MCP 서버를 Cursor AI와 통합하는 가이드
  • Windsurf 통합 - TomTom Maps MCP 서버를 사용하도록 Windsurf를 구성하는 방법
  • Smolagents 통합 - Smolagents AI 에이전트를 TomTom Maps MCP 서버에 연결하는 방법을 보여주는 예시

기본적으로 MCP 도구들은 위에 나열된 TomTom Maps API를 사용합니다. 또한 동일한 도구들에 대해 TomTom Orbis Maps를 사용하는 것도 지원합니다. 모든 도구에 대해 TomTom Orbis Maps를 활성화하려면 환경 변수 MAPS=tomtom-orbis-maps를 설정하세요.

참고: Orbis Maps 백엔드에는 TomTom Maps의 모든 도구와 더불어 다음과 같은 Orbis 전용 추가 도구들이 포함되어 있습니다: tomtom-ev-routing, tomtom-search-along-route, tomtom-area-search, tomtom-ev-search, 그리고 tomtom-data-viz

tomtom-static-map 도구는 기본 TomTom Maps 백엔드에서만 사용할 수 있습니다.

동적 지도 (dynamic map) 도구는 TomTom (TomTom Maps 또는 TomTom Orbis Maps 중 하나)으로부터 래스터 타일 (raster tiles)을 가져온 다음, skia-canvas (서버 측)를 사용하여 다음 작업을 수행합니다:

  • 적절한 줌 레벨 (zoom level)에서 지도 타일들을 하나의 캔버스 (canvas)로 병합
  • 마커 (markers), 경로 (routes), 폴리곤 (polygons) 및 기타 오버레이 (overlays) 추가
  • 최종 합성된 이미지 렌더링

서버는 렌더링된 이미지를 PNG로 변환하여 Base64 문자열로 반환합니다.

참조:

내장된 디버그 UI를 사용하면 AI 클라이언트 없이도 MCP 도구와 대화형 지도 위젯 (interactive map widgets)을 시각적으로 테스트할 수 있습니다.

npm run ui

이 명령은 MCP HTTP 서버 (포트 3000)와 디버그 UI 호스트 (포트 8080)를 모두 시작합니다. 브라우저에서 http://localhost:8080을 여세요.

도구 브라우저 (Tool browser)— 사용 가능한 모든 도구 목록을 보여주는 검색 가능한 사이드바이며, 아이콘을 통해 지도 기능이 있는 도구와 일반 도구를 구분합니다.
사전 채워진 예시 (Pre-filled examples)— 각 도구는 예시 파라미터(지도 위젯을 위한 show_ui: true 포함)와 함께 로드됩니다.
라이브 지도 위젯 (Live map widgets)— UI 리소스가 있는 도구는 브라우저에서 직접 대화형 TomTom 지도를 렌더링합니다.
응답 메타데이터 (Response metadata)— 모든 호출에 대한 지연 시간 (latency), 페이로드 크기 (payload size), 예상 토큰 수 (estimated token count), 콘텐츠 파트 (content parts) 및 타임스탬프를 제공합니다.
다크 / 라이트 모드 (Dark / light mode)— 테마 버튼으로 전환하거나 시스템 설정을 따릅니다.
키보드 단축키 (Keyboard shortcuts)— 실행하려면 Cmd+Enter, 도구 검색을 하려면 Cmd+K

  • MCP 서버가 HTTP 모드로 실행 중이어야 합니다 (npm run ui에 의해 자동으로 처리됨)
  • .env 파일에 유효한 TOMTOM_API_KEY가 있어야 합니다
  • 지도 위젯을 보려면 TomTom Orbis Maps 백엔드를 사용해야 합니다 (.env 파일에 MAPS=tomtom-orbis-maps 설정)
npm run ui:build # 의존성 설치 + UI 빌드
cd ui && npm start # UI 호스트만 시작 (MCP 서버가 이미 실행 중이라고 가정)

git clone https://github.com/tomtom-international/tomtom-maps-mcp.git
cd tomtom-maps-mcp
npm install
...

npm run build # TypeScript 빌드
npm test # 모든 테스트 실행
npm run test:unit # 단위 테스트 (Unit tests)만 실행
...

중요: 모든 테스트는 .env 파일에 유효한 API 키가 필요합니다.

테스트가 실제 API 호출을 수행하기 때문입니다 (모킹(Mocked)되지 않음). 이로 인해 API 할당량(Quota)이 소모됩니다.

src/
├── apps/ # MCP App UI 리소스
├── handlers/ # 요청 핸들러 (Request handlers)
...

echo $TOMTOM_API_KEY # 설정 여부 확인

ls -la .env # .env 존재 여부 확인
cat .env # API 키 확인

npm run build # 재빌드
npm cache clean --force # 캐시 삭제

"missing permissions"라는 오류가 나타나면, 귀하의 API 키가 TomTom Orbis Maps 또는 EV 서비스에 접근할 권한이 없음을 의미합니다.

참고: TomTom Orbis Maps 및 특정 EV 라우팅 기능은 현재 Public Preview (공개 미리보기) 단계에 있습니다. 기본적으로 모든 개발자 계정에서 사용 가능하지 않을 수 있습니다.

문제 해결 방법:

  • TomTom Developer Portal에 로그인합니다.
  • 귀하의 API 키에 **사용 가능한 모든 제품 (all available products)**이 선택되어 있는지 확인합니다.
  • MAPS=tomtom-orbis-maps를 사용할 때 여전히 403 오류가 발생한다면, 귀하의 계정이 아직 Orbis 미리보기 권한을 가지고 있지 않을 수 있습니다. 그동안은 표준 tomtom-maps 백엔드를 계속 사용할 수 있습니다.

TomTom Maps MCP Server에 대한 기여를 환영합니다! Pull Request 제출, 이슈 보고 및 개선 제안 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참조하십시오.

모든 기여는 우리의 행동 강령(Code of Conduct)을 준수해야 하며, 개발자 출처 증명(DCO, Developer Certificate of Origin)에 따라 서명되어야 합니다.

GitHub 저장소의 Open issues

보안 취약점 보고 및 보안 관행에 대한 정보는 보안 정책(Security Policy)을 참조하십시오.

이 프로젝트는 Apache License 2.0 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE.md 파일을 참조하십시오.

Copyright (C) 2025 TomTom Navigation B.V.

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0