Mapbox

Mapbox MCP Server

Mapbox API용 Model Context Protocol (MCP)을 구현하는 Node.js 서버입니다.

AI 애플리케이션에 지리 공간 인텔리전스 제공

Mapbox MCP Server는 Mapbox의 포괄적인 위치 인텔리전스 플랫폼에 원활하게 액세스할 수 있도록 하여 모든 AI 에이전트나 애플리케이션을 지리 공간을 인식하는 시스템으로 바꿔 줍니다. 이 서버를 사용하면 AI가 장소를 이해하고 추론하며, 물리적 세계를 탐색하고, 다음과 같은 풍부한 지리 공간 데이터에 액세스할 수 있습니다.

• 전 세계 지오코딩으로 주소와 장소 이름을 좌표로 변환하거나 그 반대로 변환
• 관심 지점(POI) 검색으로 전 세계 수백만 개의 업체, 랜드마크, 장소 검색
• 실시간 교통 정보를 제공하는 운전, 도보, 자전거용 멀티모달 경로 안내
• 접근성을 분석하고 물류를 최적화하는 이동 시간 행렬
• 여러 경유지를 방문하는 최적의 순서를 찾는 경로 최적화(외판원 문제)
• GPS 궤적을 도로망에 맞춰 깔끔하게 경로를 시각화하는 지도 매칭
• 특정 시간 또는 거리 제약 내에서 도달할 수 있는 영역을 시각화하는 등시간선 생성
• 실시간 대화형 지도 렌더링(render_map_tool)으로 채팅 내 실제 Mapbox GL JS 지도에 경로, 검색 결과, 사용자 지정 GeoJSON 표시
• 위치, 경로, 지리 데이터를 시각적으로 표현하는 정적 지도 이미지
• API 호출 없이 거리, 면적, 방위각, 버퍼, 공간 분석을 수행하는 오프라인 지리 공간 계산

AI 여행 도우미, 물류 최적화 도구, 위치 기반 추천 시스템 또는 "어디"인지 이해해야 하는 애플리케이션을 구축하든, Mapbox MCP Server는 이를 가능하게 하는 공간 인텔리전스를 제공합니다. Claude Desktop 및 VS Code와 같은 인기 클라이언트에서도 사용할 수 있습니다. 자세한 내용은 아래를 참조하세요.

사용법

이 MCP 서버를 사용하려면 Mapbox 액세스 토큰이 필요합니다.

호스팅 MCP 엔드포인트

빠르게 사용하려면 호스팅 MCP 엔드포인트를 이용할 수 있습니다.

엔드포인트: https://mcp.mapbox.com/mcp

클라이언트별 상세 설정 안내와 API 사용법은 호스팅 MCP Server 가이드를 참조하세요.

Mapbox 액세스 토큰을 발급받으려면 다음 단계를 따르세요.

1. mapbox.com/signup에서 무료 Mapbox 계정을 만듭니다.
2. 계정 페이지로 이동합니다.
3. 새 토큰을 만들거나 기본 공개 토큰을 사용합니다.

Mapbox 액세스 토큰에 대한 자세한 내용은 액세스 토큰에 관한 Mapbox 문서를 참조하세요.

통합 가이드

각 통합의 상세 설정 안내는 다음 가이드를 참조하세요.

• Claude Desktop 설정 - Claude Desktop에서 이 MCP 서버를 사용하도록 구성하는 방법
• Goose 설정 - Goose AI 에이전트 프레임워크 설정
• VS Code 설정 - Visual Studio Code에서 개발 환경 설정
• Cursor AI IDE 설정 - Cursor AI IDE에서 개발 환경 설정
• Smolagents 통합 - Smolagents AI 에이전트를 Mapbox 도구에 연결하는 예제
• 도구 직접 가져오기 - MCP 서버를 실행하지 않고 자체 애플리케이션에서 Mapbox 도구 사용
• render_map_tool 가이드 - 지도 시각화 프리미티브: 전체 페이로드 스키마와 다른 Mapbox 도구 없이 자체 데이터를 독립적으로 렌더링하는 방법
• 사용자 확인 요청 - search_and_geocode_tool 및 directions_tool이 사용자에게 결과를 명확히 하거나 경로를 선택하도록 요청하는 방법과 클라이언트가 이를 지원하지 않을 때 원활하게 대체하는 방법

프롬프트 예시

설정 후 Claude Desktop 또는 다른 MCP 클라이언트에서 다음 프롬프트를 사용해 보세요.

위치 기반 정보

좌표를 중심으로 하는 질문, 즉 "내 주변에 뭐가 있지", "여기는 어떤 동네야", _"N분 안에 어디까지 갈 수 있어"_와 같은 질문에는 ground_location_tool를 사용하세요. 이 도구는 역지오코딩, 카테고리 검색, 등시간선을 한 번의 호출로 조합하고, 질문에 따라 적절한 전략을 선택적으로 적용합니다. 또한 인용 정보와 함께 유형이 지정된 레코드(이름, 주소, 좌표, 거리, 도달 가능 영역 폴리곤)를 반환합니다.

아래 네 가지 프롬프트는 각각 한 번의 도구 호출로 서로 다른 전략을 실행합니다.

• 동네 — "47.6097, -122.3408은 어떤 동네이고, 내 주변에는 뭐가 있어?"
• POI — "40.7580, -73.9855에서 도보 10분 이내의 커피숍"
• 지역 — "37.7749, -122.4194에서 도보 15분 이내에 어디까지 갈 수 있어?"
• 경로 안내 — "34.0522, -118.2437에서 사람을 내려주기 가장 가까운 경로 접근 가능 지점"

위치 탐색

• "엠파이어 스테이트 빌딩에서 걸어갈 수 있는 거리에 있는 커피숍을 찾아줘"
• "시애틀에서 포틀랜드까지 가려고 하는데, 가는 길에 스타벅스가 있어?"
• "보스턴에서 뉴욕까지 가는 경로에 있는 주유소를 보여줘"
• "타임스 스퀘어 근처에 어떤 식당이 있어?"

내비게이션 및 이동

• "현재 교통 상황을 반영해 LAX에서 할리우드까지 운전 경로를 안내해줘"
• "센트럴 파크에서 타임스 스퀘어까지 걸으면 얼마나 걸려?"
• "출퇴근 시간에 택시로 내 호텔(Four Seasons)에서 JFK 공항까지 이동하는 시간을 계산해줘"

시각화 및 지도

• "Mapbox 지도 렌더링 도구를 사용해 샌프란시스코의 금문교에서 유니언 스퀘어까지 경로를 보여줘" — 실제 Mapbox 지도에 실시간 대화형 경로를 렌더링합니다.
• "금문교에서 피셔맨스 워프까지의 경로를 양쪽 위치의 마커와 함께 보여주는 지도 이미지를 만들어줘"
• "주요 랜드마크를 표시한 맨해튼 위성 지도를 보여줘"
• "시애틀 도심에서 1마일 이내에 있는 모든 스타벅스 위치를 강조하는 지도를 만들어줘"
• "이 좌표 위에 채움 폴리곤을 표시하고, [...]에 'Warehouse'라는 레이블이 붙은 마커를 추가해줘" — 다른 Mapbox 도구 없이 render_map_tool을 통해 자체 GeoJSON을 직접 렌더링합니다.

분석 및 계획

• "포틀랜드 도심에서 자동차로 30분 이내에 갈 수 있는 지역을 보여줘"
• "덴버의 이 호텔 3곳(Marriott, Sheraton, Hilton)과 컨벤션 센터 사이의 이동 시간 행렬을 계산해줘"
• "샌프란시스코의 이 관광 명소 3곳(금문교, Musical Stairs, Fisherman's Wharf)을 방문하는 최적 경로를 찾아줘"
• "다음 주소 8곳을 방문하는 배송 경로를 최적화해줘: [주소 목록]"

GPS 및 경로 매칭

• "이 GPS 궤적을 정리하고 도로를 따라가는 실제 경로를 보여줘: [타임스탬프가 포함된 좌표 목록]"
• "기록된 자전거 주행 경로를 자전거 도로망에 맞춰줘: [GPS 좌표]"
• "이 운전 경로를 도로망에 맞추고 교통 혼잡도를 보여줘"

오프라인 지리 공간 계산

• "이 두 좌표 사이의 거리는 몇 마일이야?"
• "이 폴리곤의 면적을 제곱킬로미터로 계산해줘"
• "37.7749°N, 122.4194°W 지점은 이 서비스 지역 폴리곤 안에 있어?"
• "샌프란시스코에서 뉴욕까지의 방위각은 얼마야?"
• "런던과 파리의 중간 지점을 찾아줘"
• "이 위치를 중심으로 반경 5마일의 버퍼 영역을 만들어줘"
• "이 동네 경계의 중심점을 계산해줘"
• "이 경로 좌표의 경계 상자는 어떻게 돼?"
• "점의 개수를 줄이도록 이 복잡한 폴리곤을 단순화해줘"

더 나은 결과를 위한 팁

• 위치를 구체적으로 지정하세요(전체 주소나 랜드마크 이름 사용).
• 선호하는 이동 수단을 지정하세요(운전, 도보, 자전거).
• 관련이 있다면 시간 제약을 포함하세요("출퇴근 시간", "오후 3시").
• 필요한 경우 원하는 출력 형식을 요청하세요("지도 이미지로", "JSON 형식으로").

자세한 예시: 다양한 사용 사례와 MCP Inspector 테스트 안내가 포함된 경로 주변 검색 프롬프트의 종합적인 예시는 examples/search-along-route.md를 참조하세요.

리소스

MCP 서버는 정적 참조 데이터를 MCP 리소스로 제공합니다. 리소스를 사용하면 도구를 호출하지 않고도 클라이언트가 직접 참조할 수 있는 데이터에 읽기 전용으로 액세스할 수 있습니다.

사용 가능한 리소스

Mapbox 카테고리 리소스

URI 패턴: mapbox://categories 또는 mapbox://categories/{language}

카테고리 검색 도구에서 사용할 수 있는 전체 카테고리 ID 목록에 액세스합니다. 카테고리를 사용하면 유형(예: "restaurant", "hotel", "gas_station")별로 검색 결과를 필터링할 수 있습니다.

예시:

• mapbox://categories - 기본(영어) 카테고리 목록
• mapbox://categories/ja - 일본어 카테고리 이름
• mapbox://categories/es - 스페인어 카테고리 이름

리소스 액세스 방법:

• 기본 MCP 리소스를 지원하는 클라이언트: resources/read MCP 프로토콜 메서드 사용
• 리소스를 지원하지 않는 클라이언트: 리소스 URI와 함께 resource_reader_tool 사용

풍부한 지도 미리보기 (render_map_tool)

이 서버의 모든 지리 공간 도구(경로 안내, 등시간선, 검색 등)는 **render_map_tool**를 통해 결과를 실시간 대화형 Mapbox GL JS 지도로 표시할 수 있습니다. 이는 서버의 단일 시각화 프리미티브입니다. 지원되는 클라이언트에서는 MCP Apps 프로토콜(@modelcontextprotocol/ext-apps)을 통해 채팅 내에 전체 화면 전환 기능이 있는 독립형 HTML 패널로 렌더링됩니다.

• Claude Desktop ✅
• GitHub Copilot이 포함된 VS Code ✅
• Claude Code ✅
• Goose ✅

이 기능을 사용하기 위해 이 서버의 다른 도구는 필요하지 않습니다. render_map_tool는 직접 작성한 GeoJSON도 지원하므로, 다른 도구에 의존하지 않고 자체 폴리곤, 마커, 경로를 표시할 수 있습니다. directions_tool, isochrone_tool 또는 다른 Mapbox API 호출도 필요하지 않습니다. 페이로드 스키마와 완전한 독립 실행형 예시는 **전체 render_map_tool 가이드**를 참조하세요.

MCP Apps를 지원하지 않는 클라이언트에서 정적 이미지를 확실하게 표시해야 한다면 대신 static_map_image_tool을 사용하세요. 모든 클라이언트에서 표시할 수 있는 base64 인코딩 PNG/JPEG를 반환합니다.

CLIENT_NEEDS_RESOURCE_FALLBACK

리소스 대체 도구(비준수 클라이언트용 선택 사항)

리소스는 대부분의 클라이언트(Claude Desktop, VS Code, MCP Inspector 등)가 지원하는 MCP의 핵심 기능입니다. 하지만 일부 클라이언트(예: smolagents)는 리소스를 전혀 지원하지 않습니다. 이러한 클라이언트에서는 서버가 도구 호출을 통해 리소스와 동일한 콘텐츠를 제공하는 "리소스 대체 도구"를 제공할 수 있습니다.

대체 도구:

• resource_reader_tool - URI로 모든 리소스를 읽는 범용 대체 도구
• category_list_tool - 카테고리 목록(mapbox://categories)에 액세스

기본적으로 이 도구는 포함되지 않습니다(클라이언트가 리소스를 지원한다고 가정). 클라이언트가 리소스를 지원하지 않는 경우 대체 도구를 활성화하세요.

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

다음과 같은 경우 설정하세요.

• ✅ smolagents 또는 리소스를 지원하지 않는 다른 클라이언트를 사용하는 경우 true로 설정
• ❌ Claude Desktop, VS Code, MCP Inspector 또는 리소스를 지원하는 클라이언트를 사용하는 경우 설정하지 않음(기본값)
• ❌ 확실하지 않은 경우 설정하지 않음(대부분의 클라이언트는 리소스를 지원함)

도구

유틸리티 도구

리소스 리더 도구

기본 MCP 리소스 API를 지원하지 않는 클라이언트에 MCP 리소스 액세스를 제공합니다. 이 도구를 사용해 카테고리 목록과 같은 리소스를 읽을 수 있습니다.

매개변수:

• uri: 읽을 리소스 URI(예: mapbox://categories, mapbox://categories/ja)

사용 예시:

• 기본 카테고리 읽기: {"uri": "mapbox://categories"}
• 일본어 카테고리 읽기: {"uri": "mapbox://categories/ja"}

참고: MCP 클라이언트가 기본 리소스를 지원한다면 성능 향상을 위해 리소스 API를 직접 사용하는 것이 좋습니다.

오프라인 지리 공간 도구

이 도구는 Mapbox API를 호출하지 않고 완전히 오프라인으로 지리 공간 계산을 수행합니다. 정확한 지리 계산을 위해 Turf.js를 사용하며, 인터넷에 연결되지 않은 곳에서도 작동합니다.

거리 도구

Haversine 공식을 사용해 두 지리 좌표 사이의 거리를 계산합니다.

기능:

• 킬로미터, 마일, 미터, 피트, 해리 등 여러 단위 지원
• 정확한 대권 거리 계산
• API 호출 불필요

사용 예시: "샌프란시스코(37.7749°N, 122.4194°W)와 뉴욕(40.7128°N, 74.0060°W) 사이의 거리는 얼마야?"

폴리곤 내 점 도구

하나 이상의 점이 폴리곤 또는 멀티폴리곤 안에 있는지 확인하고, 내부에 있는 점만 반환합니다. 한 번의 호출로 단일 점이나 여러 점을 처리할 수 있습니다.

기능:

• 구멍이 있는 복잡한 폴리곤 지원
• 멀티폴리곤 지원
• 한 번의 호출로 원하는 수의 포인트를 일괄 테스트
• 지오펜싱, 배송 구역 검증, 고객 세분화에 유용

사용 예시: "이 배송 주소 중 서비스 지역 안에 있는 곳은 어디인가요?"

목적지 도구

측지선(대권) 오프셋을 사용해 시작점, 방위각, 거리를 기준으로 목적지 포인트를 계산합니다.

기능:

• 경로를 따라가는 것이 아닌 직선 오프셋
• "X에서 북쪽으로 5km 떨어진 지점 찾기" 또는 검색 오프셋 구성에 유용
• API 호출 불필요

사용 예시: "Space Needle에서 북동쪽으로 10km 떨어진 지점은 어디인가요?"

방위각 도구

두 좌표 사이의 나침반 방향(방위각)을 계산합니다.

기능:

• 방위각을 도 단위(0-360°)로 반환
• 기본 방위 제공(N, NE, E, SE, S, SW, W, NW)
• 내비게이션 및 방향 관련 질의에 유용

사용 예시: "여기서 공항으로 가려면 어느 방향으로 가야 하나요?"

중간점 도구

대권 경로를 따라 두 좌표 사이의 지리적 중간점을 찾습니다.

기능:

• 지구의 곡면에서 실제 중간점 계산
• 만날 장소 제안에 유용
• 장거리 계산을 정확하게 처리

사용 예시: "샌프란시스코와 뉴욕의 중간 지점은 어디인가요?"

중심점 도구

폴리곤 또는 멀티폴리곤의 기하학적 중심(중심점)을 계산합니다.

기능:

• 복잡한 도형 처리
• 모든 포인트의 산술 평균 반환
• 라벨이나 마커 배치에 유용

사용 예시: "이 동네 경계에 마커를 어디에 배치해야 하나요?"

면적 도구

폴리곤의 면적을 계산합니다.

기능:

• 여러 단위 지원: 제곱미터, 제곱킬로미터, 에이커, 헥타르, 제곱마일, 제곱피트
• 지구 표면에서 정확한 면적 계산
• 크기에 관계없이 모든 폴리곤 처리

사용 예시: "이 공원의 면적은 에이커 단위로 얼마인가요?"

경계 상자 도구

지오메트리를 포함하는 최소 경계 상자(bbox)를 계산합니다.

기능:

• 포인트, 라인, 폴리곤, 멀티폴리곤 처리
• [minLongitude, minLatitude, maxLongitude, maxLatitude] 반환
• 뷰포트 계산 및 공간 인덱싱에 유용

사용 예시: "이 경로의 경계 상자는 무엇인가요?"

버퍼 도구

포인트, 라인 또는 폴리곤 주변에 버퍼 영역(폴리곤)을 생성합니다.

기능:

• 여러 거리 단위 지원
• 포인트 주변에 원형 버퍼 생성
• 근접성 분석 및 영향권 생성에 유용

사용 예시: "이 위치 주변에 5km 버퍼 영역을 표시해 주세요"

단순화 도구

Douglas-Peucker 알고리즘을 사용해 라인 또는 폴리곤의 꼭짓점 수를 줄입니다.

기능:

• 세부 수준을 조정할 수 있는 허용 오차 설정
• 복잡도를 줄이면서 전체 형태 유지
• 파일 크기 축소 및 렌더링 성능 향상에 유용
• 위상 유지 옵션(자기 교차 방지)

사용 예시: "이 복잡한 경계를 단순화해 포인트 수를 줄여 주세요"

길이 도구

일련의 좌표로 정의된 라인의 전체 길이를 측정합니다.

기능:

• 킬로미터, 마일, 미터, 피트 지원
• 라우팅 API를 호출하지 않고 그린 경로, 트레일 또는 경계의 길이를 측정하는 데 유용

사용 예시: "이 하이킹 트레일의 길이는 얼마인가요?"

볼록 껍질 도구

포인트 집합의 볼록 껍질, 즉 모든 포인트를 포함하는 가장 작은 볼록 폴리곤을 계산합니다.

기능:

• 경계 영역 분석 또는 커버리지 영역 추정에 유용
• API 호출 없이 오프라인으로 작동

사용 예시: "이 모든 매장 위치를 포함하는 가장 작은 폴리곤은 무엇인가요?"

최근접 포인트 도구

주어진 대상 포인트에서 컬렉션 내 가장 가까운 포인트를 찾습니다.

기능:

• 각 후보에 대해 distance_tool을 호출한 뒤 정렬하는 것보다 효율적
• 위치에서 가장 가까운 매장, 정류장 또는 랜드마크를 찾는 데 유용

사용 예시: "이 매장 중 현재 위치에서 가장 가까운 곳은 어디인가요?"

라인 위 최근접 포인트 도구

포인트를 라인 또는 경로에서 가장 가까운 위치에 스냅하고, 해당 포인트와 거리를 반환합니다.

기능:

• "이 경로에서 내 위치와 가장 가까운 지점은 어디인가요?"와 같은 질의 또는 API 호출 없는 맵 매칭에 유용

사용 예시: "지금 이 하이킹 트레일에서 내가 가장 가까이 있는 지점은 어디인가요?"

합집합, 교집합, 차집합 도구

두 개 이상의 폴리곤을 결합하거나 비교합니다. union_tool은 폴리곤을 하나의 지오메트리로 병합하고, intersect_tool는 겹치는 영역을 찾으며, difference_tool은 한 폴리곤에서 다른 폴리곤을 뺍니다.

기능:

• 서비스 영역 결합, 커버리지 중첩 영역 찾기, 제외 구역 계산(예: "구역 A에는 포함되지만 구역 B에는 포함되지 않는 곳은 어디인가요?")에 유용
• 완전히 오프라인으로 작동 — API 호출 불필요
• 각 도구는 결과를 바로 시각화할 수 있도록 render_map_tool 참조를 반환

사용 예시: "이 두 배송 구역을 하나의 커버리지 영역으로 합쳐 주세요" / "이 두 등시간선이 겹치는 곳은 어디인가요?" / "이 서비스 영역 중 15분 등시간선에 포함되지 않는 부분은 어디인가요?"

Mapbox API 도구

카테고리 목록 도구(지원 중단 예정)

⚠️ 지원 중단 예정: 대신 URI mapbox://categories을 사용하는 resource_reader_tool를 사용하거나, 클라이언트가 MCP 리소스를 지원하는 경우 mapbox://categories 리소스에 직접 액세스하세요.

이 도구는 MCP 리소스 또는 resource_reader_tool을 지원하지 않는 클라이언트와의 하위 호환성을 위해 유지 관리됩니다.

매트릭스 도구

Mapbox Matrix API를 사용해 여러 포인트 간 이동 시간과 거리를 계산합니다. 주요 기능:

• 일대다, 다대일 또는 다대다 경로 계산을 효율적으로 수행
• 다양한 이동 프로필 지원(driving-traffic, driving, walking, cycling)
• 교통 상황을 반영한 계산을 위한 출발 시간 지정
• 거리 및 소요 시간 지표를 포함한 경로 요약
• 접근 방식(연석/제한 없음) 및 허용되는 출발 방위각 범위 제어

정적 이미지 도구

Mapbox static image API를 사용해 정적 지도 이미지를 생성합니다. 주요 기능:

• 사용자 지정 지도 스타일(streets, outdoors, satellite 등)
• 이미지 크기 및 확대 수준 조정
• 사용자 지정 색상과 라벨을 사용한 여러 마커 지원
• 폴리라인 및 폴리곤을 포함한 오버레이 옵션
• 지정된 좌표에 맞춰 자동으로 표시 영역 조정

카테고리 검색 도구

Mapbox Search Box category search API를 사용해 카테고리별 검색을 수행합니다. 주요 기능:

• 카테고리별 관심 지점 검색(레스토랑, 호텔, 주유소 등)
• 지리적 근접성에 따른 필터링
• 결과 수 제한 설정
• 각 결과에 대한 풍부한 메타데이터
• 여러 언어 지원

역지오코딩 도구

Mapbox geocoding V6 API를 사용해 역지오코딩을 수행합니다. 주요 기능:

• 지리 좌표를 사람이 읽을 수 있는 주소로 변환
• 세부 수준 조정(도로, 동네, 도시 등)
• 유형별 결과 필터링(주소, POI, 동네 등)
• 여러 언어 지원
• 풍부한 위치 맥락 정보

지상 위치 도구

한 번의 호출로 "이 좌표 주변에는 무엇이 있나요?"라는 질문에 답합니다. 장소 이름, 주변 관심 지점, 이동 시간 기준 도달 가능 정보를 실시간 Mapbox 데이터와 출처 정보에 기반해 제공합니다. reverse_geocode_tool와 웹 검색을 연이어 사용하는 대신 이 도구를 사용하세요.

기능:

• 질의를 분류(경로 안내, 동네 맥락, POI 검색, 지역/도달 가능성)하고 관련 데이터만 가져옴
• 요청 시 카테고리별 주변 POI 검색
• 이동 시간 기준 도달 가능성 요약(등시간선 기반)
• 위치 정보와 주변 POI가 표시된 render_map_tool 참조 반환

사용 예시: "이 좌표는 어느 동네에 있으며, 근처에 커피숍이 있나요?"

장소 세부 정보 도구

Mapbox ID를 사용해 특정 장소의 상세 정보(사진, 영업시간, 평점, 전화번호, 웹사이트 URL)를 가져옵니다. 특정 검색 결과의 세부 정보를 확인하려면 search_and_geocode_tool, category_search_tool 또는 reverse_geocode_tool 다음에 사용하세요.

사용 예시: "첫 번째 커피숍 검색 결과에 대해 더 알려 주세요. 영업시간, 전화번호, 웹사이트를 알려 주세요."

길찾기 도구

Mapbox Directions API를 사용해 경로 안내를 가져옵니다. 주요 기능:

• 다양한 경로 프로필 지원: 운전(실시간 교통 또는 일반 교통), 도보, 자전거
• 여러 경유지(좌표 쌍 2~25개)를 거치는 경로
• 대체 경로 옵션
• 경로 주석(거리, 소요 시간, 속도, 혼잡도)
• 일정 옵션:
  • 운전 및 driving-traffic 프로필의 미래 출발 시간(depart_at)
  • 운전 프로필만 지원하는 희망 도착 시간(arrive_by)
• 프로필별 최적화:
  • 운전: 차량 치수 제약(높이, 너비, 무게)
• 경로 제외 옵션:
  • 일반 제외 항목: 페리 경로, 현금 결제만 가능한 유료 도로
  • 운전 전용 제외 항목: 유료 도로, 고속도로, 비포장도로, 터널, 국가 경계, 주 경계
  • 사용자 지정 포인트 제외(피해야 할 지리적 포인트 최대 50개)
• GeoJSON 지오메트리 출력 형식

등시간선 도구

Mapbox Isochrone API를 사용해 위치에서 지정된 시간 내에 도달할 수 있는 영역을 계산합니다. 주요 기능:

• 다양한 이동 프로필 지원(운전, 도보, 자전거)
• 이동 시간 또는 거리 사용자 지정
• 여러 등고선 생성(예: 15분, 30분, 45분 범위)
• 선택적 출발 또는 도착 시간 지정
• 시각화를 위한 색상 사용자 지정

검색 및 지오코딩 도구

Mapbox Search Box Text Search API 엔드포인트를 사용해 POI, 주소, 장소 및 해당 API가 지원하는 기타 유형을 검색하고 지오코딩합니다. 이 도구는 이전 버전의 이 MCP 서버에서 ForwardGeocodeTool과 PoiSearchTool이 제공하던 기능을 하나의 도구로 통합합니다.

맵 매칭 도구

Mapbox Map Matching API를 사용해 GPS 궤적을 도로망에 스냅합니다. 주요 기능:

• 노이즈가 있는 GPS 궤적을 도로망의 정확한 경로로 변환
• 다양한 이동 프로필 지원(운전, driving-traffic, 도보, 자전거)
• 요청당 최대 100개의 좌표 쌍 처리
• 속도 기반 정확도 향상을 위한 선택적 타임스탬프
• GPS 품질 수준별 스냅 반경 설정
• 경로 주석(제한 속도, 거리, 소요 시간, 교통 혼잡도)
• 여러 지오메트리 출력 형식(GeoJSON, polyline)

사용 예시: "이 GPS 궤적을 정리하고 도로에 스냅해 주세요: [타임스탬프가 포함된 좌표]"

최적화 도구

Mapbox Optimization API를 사용해 여러 위치를 거치는 최적 경로를 찾습니다. 주요 기능:

• 2~12개 위치에 대한 외판원 문제(TSP) 해결
• 다양한 이동 프로필 지원(운전, driving-traffic, 도보, 자전거)
• 유연한 출발점 및 도착점 설정
• 왕복 또는 편도 경로 최적화
• 회전별 내비게이션 안내(선택 사항)
• 경로 주석(거리, 소요 시간, 속도)
• 여러 지오메트리 출력 형식(GeoJSON, polyline)

사용 예시: "이 5개 경유지를 방문하는 최적 경로를 찾아 주세요: [주소 또는 좌표 목록]"

참고: 시간대, 용량 제약, 여러 차량 등 고급 기능을 제공하는 V2 API를 사용할 수 있지만 베타 액세스가 필요합니다. V2 구현은 코드베이스에 포함되어 있지만 기본적으로 등록되어 있지 않습니다.

피드백 도구

Mapbox Feedback API(공개 프리뷰)를 통해 앱 또는 에이전트에 대한 사용자의 피드백을 개발자에게 전송합니다. 피드백은 액세스 토큰을 소유한 계정에 등록됩니다. 따라서 이 서버에서 자체 토큰을 사용해 앱이나 에이전트를 구축하면 사용자의 피드백이 앱의 Feedback Agent 보고서와 같은 피드에 표시되며, Feedback Explorer에서 검토할 수 있습니다. Mapbox에 문제를 신고하는 기능은 아닙니다. Feedback Agent와 마찬가지로, 사용자의 요구를 파악하는 데 도움이 되는 제품 관련 피드백을 위한 기능입니다. 예를 들면 다음과 같습니다:

• 폐업했거나, 정보가 잘못되었거나, 위치가 잘못된 장소
• 찾을 수 없는 장소 또는 주소
• 폐쇄된 도로, 잘못된 제한 속도 또는 잘못 표시된 교통 정보
• 불법 회전이나 진입이 포함된 경로 또는 경로가 전혀 없는 경우
• 버그나 제안 등 앱 자체에 관한 내용 (application_issue)

피드백 내용, 카테고리, 위치를 전송하고 항목의 ID와 상태를 반환합니다. 장소에 관한 피드백이 아닌 경우 위치는 선택 사항입니다. API에서는 위치가 필수이므로, 현재 Feedback API 팀의 권고에 따라 도구는 0, 0을 전송합니다. 사용자가 승인하지 않으면 아무것도 전송되지 않습니다. 사용자 확인 요청을 지원하는 클라이언트는 먼저 확인 메시지를 표시하고, 그 외의 경우에는 도구 설명에서 모델이 채팅으로 확인하도록 요청합니다.

Feedback API는 Public Preview 기간 동안 무료입니다. General Availability부터 Feedback Agent는 피드백 항목당 $0.02를 청구합니다. 같은 문제를 두 번 제출하지 않도록 도구는 전송 전에 지난 30일간 계정에서 제출한 보고서를 확인합니다. 같은 카테고리의 보고서가 50 m 이내에 있고 아직 검토 대기 중이면(위치가 없는 피드백은 확인하지 않음), 새 보고서를 전송하는 대신 해당 보고서를 반환합니다. Feedback API에는 계정 소유자의 보고서만 표시되므로 다른 계정의 보고서는 확인할 수 없습니다. 사용자가 자신의 보고서와 다른 문제라고 말하면 send_anyway: true이 확인을 건너뜁니다.

요구 사항: 전송하려면 액세스 토큰에 user-feedback:write 범위가 필요하고, 중복 확인에는 user-feedback:read 범위가 필요합니다. 쓰기 범위가 없으면 도구는 이를 알리는 오류를 반환합니다. 읽기 범위가 없으면 확인 없이 전송하고 결과에 그 사실을 알립니다. 도구를 제외하려면 --disable-tools feedback_tool을 사용해 서버를 시작합니다.

사용 예: "Mint St의 Blue Bottle은 작년에 폐업했어요. 이 내용을 피드백으로 보내 주시겠어요?"

Report 도구

Mapbox MCP 서버 자체에 관한 버그, 잘못되거나 혼란스러운 결과를 반환한 도구, 누락된 기능 또는 제안 등의 피드백을 서버를 개발하는 Mapbox 팀에 전송합니다. 이 피드백은 사용자의 계정이 아닌 Mapbox 자체 계정으로 제출되므로 추가 토큰 범위가 필요하지 않으며, 제출 후에는 다시 확인하거나 철회할 수 없습니다. 잘못된 지도, 장소 또는 경로 데이터를 신고하는 용도가 아닙니다.

서버는 피드백 내용 끝에 서버 버전, 클라이언트 이름과 버전, 피드백 대상 도구를 추가합니다. 사용자가 승인하지 않으면 아무것도 전송되지 않습니다. 사용자 확인 요청을 지원하는 클라이언트는 먼저 확인 메시지를 표시하고, 그 외의 경우에는 도구 설명에서 모델이 채팅으로 확인하도록 요청합니다.

Feedback API 팀이 Mapbox CLI의 mapbox report 명령을 위해 추가한 엔드포인트를 사용합니다. 도구를 제외하려면 --disable-tools report_tool을 사용해 서버를 시작합니다.

사용 예: "지도에 등시선이 하나도 표시되지 않았어요. Mapbox MCP 팀에 알려 주시겠어요?"

공개 토큰 목록 도구

채팅 외부에서 Mapbox GL JS를 로드하거나 브라우저에서 Mapbox API를 호출하는 웹 페이지 또는 앱을 만드는 에이전트를 위해 계정의 공개 (pk.) 액세스 토큰을 나열합니다. 채팅 내에서는 render_map_tool에 토큰이 필요하지 않습니다. 각 토큰에는 이름, 기본 토큰 여부, URL 제한 및 범위가 포함됩니다.

페이지가 실행될 위치인 site_url을 전달하면, 계정에 해당 URL로 제한된 토큰이 있는 경우 도구가 이를 추천합니다. 그렇지 않으면 기본 공개 토큰을 추천하고, 공개 사이트에는 URL 제한 토큰을 사용해야 한다고 알리며 토큰을 만들 수 있는 링크를 제공합니다. 제한되지 않은 공개 토큰을 복사한 사람은 누구나 사용할 수 있으며, 사용 요금은 계정에 청구됩니다.

비밀 토큰이나 임시 토큰은 반환하지 않으며, 토큰을 만들 수도 없습니다(이를 위해서는 tokens:write이 필요하며, DevKit server의 create_token_tool이 토큰을 생성합니다).

요구 사항: 목록을 조회하려면 tokens:read 범위가 필요합니다. 이는 채팅 내 지도에서 기본 공개 토큰을 찾을 때 사용하는 것과 같은 범위입니다. pk. 액세스 토큰을 사용하거나 서버 자체의 MAPBOX_ACCESS_TOKEN에서 목록 조회에 실패하고 MAPBOX_PUBLIC_TOKEN이 설정된 경우, 해당 토큰을 대신 반환합니다. 자체 bearer 토큰을 사용하는 호출자(호스팅 서버)에게는 MAPBOX_PUBLIC_TOKEN이 반환되지 않으며, 다른 URL로 제한된 토큰은 추천되지 않습니다. 도구를 제외하려면 --disable-tools list_public_tokens_tool을 사용해 서버를 시작합니다.

사용 예: "Mapbox 지도를 사용해 매장 세 곳의 위치를 표시하는 단일 페이지 사이트를 만들어 주세요."

개발

서버 검사

Node.js 사용

# Run the built image
npm run inspect:build

Docker 사용

# Build the Docker image
docker build -t mapbox-mcp-server .

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

새 도구 만들기

npx plop create-tool
# provide tool name without suffix (e.g. Search)

새 버전 릴리스

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

중요: 게시자 워크플로는 package.json과 server.json의 버전이 릴리스 버전과 일치하는지 확인합니다. 버전 업데이트나 매니페스트 동기화를 건너뛰면 게시에 실패합니다.

OpenTelemetry 추적

이 MCP 서버에는 프로덕션 환경의 관측 가능성을 위한 포괄적인 OpenTelemetry 추적 기능이 포함되어 있습니다.

빠른 데모

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

참고: 서버는 시작 시 .env 파일에서 구성을 자동으로 불러옵니다. .env.example 파일에는 여러 관측 가능성 플랫폼의 구성 예제가 포함되어 있습니다.

지원되는 관측 가능성 플랫폼

.env.example에 다음 구성 예제가 포함되어 있습니다.

클라우드 제공업체:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

SaaS 플랫폼:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 모든 OTLP 호환 백엔드

프로덕션 구성

전체 설정 안내는 docs/tracing.md를 참조하세요. 다음 내용이 포함되어 있습니다.

• 🔧 플랫폼별 구성 가이드
• 📊 인증 및 엔드포인트 설정
• 🎯 사용자 지정 추적 속성 및 컨텍스트
• 🚀 성능 최적화(오버헤드 최소화)
• 🔍 문제 해결 및 디버깅

추적 기능:

• ✅ 구성 로드 추적(.env 파일 로드)
• ✅ 도구 실행 자동 추적
• ✅ CloudFront 상관관계 ID를 포함한 HTTP 요청 계측
• ✅ 구성 가능한 내보내기 도구(console, OTLP)
• ✅ 보안을 고려한 설계(데이터 보호, JWT 검증)
• ✅ 프로덕션 환경에 적합(<1% CPU 오버헤드)

기여

Mapbox MCP Server에 기여해 주셔서 감사합니다! pull request를 제출하기 전에 CONTRIBUTING.md를 읽어 주세요.

전체 표준 및 가이드라인:

• CONTRIBUTING.md - 시작하기, PR 절차, 빠른 참조
• Engineering Standards (docs/engineering_standards.md) - 코드 품질, 테스트, 문서화 및 협업에 관한 전체 표준
• Claude Code Guide (CLAUDE.md) - Claude Code를 사용하는 기여자를 위한 표준 및 패턴
• AI Agent Instructions (AGENTS.md) - 다른 AI 코딩 어시스턴트(Cursor, Continue, Aider 등)를 위한 가이드
• GitHub Copilot Guidelines - GitHub Copilot을 책임감 있게 사용하기 위한 모범 사례

기여자 빠른 시작

1. 저장소를 포크하고 포크한 저장소를 클론합니다.
2. 종속성을 설치합니다: npm install
3. 코딩 표준에 따라 변경 사항을 적용합니다.
4. 테스트와 린트를 실행합니다: npm test && npm run lint
5. 새 기능을 추가했다면 테스트를 작성합니다.
6. 명확한 설명과 함께 pull request를 제출합니다.

모든 기여는 CI 검사와 코드 리뷰 절차를 통과해야 합니다. 자세한 요구 사항은 docs/engineering_standards.md를 참조하세요.

데이터 사용 및 개인정보 보호

Mapbox API로 전송되는 데이터

MCP 서버 도구를 사용하면 다음 데이터가 사용자 환경에서 Mapbox API로 직접 전송됩니다.

• 지오코딩 도구: 주소/위치 텍스트, 좌표, 국가/지역 필터
• 검색 도구: 검색어, 근접 검색을 위한 위치 좌표, 카테고리 필터
• 길찾기 도구: 시작/종료 좌표, 경유지, 경로 설정, 차량 제약 조건
• 매트릭스 도구: 여러 좌표 쌍, 이동 프로필, 출발 시간
• 정적 지도 도구: 좌표, 확대/축소 수준, 스타일 설정, 마커 정보
• 등시선 도구: 출발지 좌표, 시간/거리 매개변수, 이동 프로필

개인정보 보호

• 로컬 실행: 모든 API 호출은 사용자 환경에서 Mapbox API로 직접 이루어집니다.
• 토큰 보안: Mapbox API 토큰은 로컬 컴퓨터에 보관되며 이 MCP 서버로 전송되거나 서버에 저장되지 않습니다.
• 데이터 저장 안 함: 이 MCP 서버는 사용자의 데이터나 API 요청을 저장, 기록 또는 수집하지 않습니다.
• 직접 통신: 사용자와 Mapbox API 사이에 중개 서버가 없습니다.

제3자 데이터 사용

• Mapbox 개인정보 처리방침은 Mapbox API로 전송되는 데이터에 적용됩니다: https://www.mapbox.com/legal/privacy/
• API 사용: 이 도구를 통해 이루어지는 모든 요청에는 표준 Mapbox API 약관이 적용됩니다.
• 데이터 보존: Mapbox의 데이터 보존 정책은 Mapbox 문서를 참조하세요.

지원 및 문의

MCP 서버 문제

• 이메일: mcp-feedback@mapbox.com
• GitHub Issues: 버그 및 기능 요청 신고

Mapbox API 문의

• Mapbox 지원: https://support.mapbox.com/
• 문서: https://docs.mapbox.com/
• API 상태: https://status.mapbox.com/

유지 관리 약속

이 MCP 서버는 Mapbox, Inc.에서 공식적으로 유지 관리합니다. 다음을 제공합니다.

• 새로운 Mapbox API 기능에 대한 정기 업데이트
• 버그 수정 및 보안 업데이트
• 최신 MCP 프로토콜 버전과의 호환성
• GitHub 이슈를 통한 커뮤니티 지원

---

MIT License