Mapbox

Mapbox MCP 서버

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

AI 애플리케이션을 위한 지리공간 인텔리전스 활용

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

• 전 세계 지오코딩 - 주소와 장소 이름을 좌표로, 좌표를 주소와 장소 이름으로 변환
• 관심 지점(POI) 검색 - 전 세계 수백만 개의 업체, 랜드마크, 장소 검색
• 다중 모드 경로 안내 - 실시간 교통 정보를 포함한 운전, 도보, 자전거 경로
• 이동 시간 매트릭스 - 접근성 분석 및 물류 최적화
• 경로 최적화 - 여러 경유지의 최적 방문 순서 찾기(외판원 문제)
• 지도 매칭 - GPS 추적을 도로 네트워크에 스냅하여 깔끔한 경로 시각화
• 등시권 생성 - 특정 시간 또는 거리 제약 내에 도달 가능한 영역 시각화
• 실시간 대화형 지도 렌더링 (render_map_tool) - 실제 Mapbox GL JS 지도에서 채팅 내에서 직접 경로, 검색 결과, 사용자 정의 GeoJSON 표시
• 정적 지도 이미지 - 위치, 경로, 지리 데이터의 시각적 표현 생성
• 오프라인 지리공간 계산 - API 호출 없이 거리, 면적, 방위각, 버퍼, 공간 분석 수행

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

사용법

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

호스팅된 MCP 엔드포인트

빠른 접근을 위해 호스팅된 MCP 엔드포인트를 사용할 수 있습니다:

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

다양한 클라이언트 및 API 사용에 대한 자세한 설정 지침은 호스팅된 MCP 서버 가이드를 참조하세요.

Mapbox 액세스 토큰을 얻으려면:

1. mapbox.com/signup에서 무료 Mapbox 계정에 가입하세요.
2. 계정 페이지로 이동하세요.
3. 새 토큰을 생성하거나 기본 공개 토큰을 사용하세요.

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

통합 가이드

다양한 통합에 대한 자세한 설정 지침은 다음 가이드를 참조하세요:

• Claude Desktop 설정 - 이 MCP 서버와 함께 작동하도록 Claude Desktop을 구성하는 지침
• Goose 설정 - Goose AI 에이전트 프레임워크 설정
• VS Code 설정 - Visual Studio Code에서 개발 환경 설정
• Cursor AI IDE 설정 - Cursor AI IDE에서 개발 환경 설정
• Smolagents 통합 - Smolagents AI 에이전트를 Mapbox 도구에 연결하는 방법을 보여주는 예제
• 도구 직접 가져오기 - MCP 서버를 실행하지 않고 자체 애플리케이션에서 Mapbox 도구 사용
• render_map_tool 가이드 - 지도 시각화 기본 요소: 전체 페이로드 스키마 및 다른 Mapbox 도구 없이 자체 데이터를 독립적으로 렌더링하는 방법
• Elicitations - 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에서 할리우드까지 운전 경로 안내"
• "센트럴 파크에서 타임스퀘어까지 도보로 얼마나 걸리나요?"
• "러시아워에 호텔(포시즌스)에서 JFK 공항까지 택시로 이동 시간 계산"

시각화 및 지도

• "Mapbox 지도 렌더 도구를 사용하여 샌프란시스코의 골든 게이트 브리지에서 유니언 스퀘어까지 경로 표시" — 실제 Mapbox 지도에서 실시간 대화형 경로 렌더링
• "골든 게이트 브리지에서 피셔맨스 워프까지의 경로와 양쪽 위치에 마커가 있는 지도 이미지 생성"
• "주요 랜드마크가 표시된 맨해튼 위성 보기 표시"
• "시애틀 다운타운에서 1마일 이내의 모든 스타벅스 위치를 강조하는 지도 생성"
• "다음 좌표에 채우기 폴리곤 표시: [...], '창고'라는 라벨의 마커 포함 [...]" — render_map_tool을 통해 자체 GeoJSON을 직접 렌더링, 다른 Mapbox 도구 불필요

분석 및 계획

• "포틀랜드 다운타운에서 자동차로 30분 내 도달 가능한 지역 표시"
• "덴버의 이 3개 호텔 위치(메리어트, 쉐라톤, 힐튼)와 컨벤션 센터 간 이동 시간 매트릭스 계산"
• "샌프란시스코의 이 3개 관광 명소(골든 게이트, 뮤지컬 계단, 피셔맨스 워프)를 방문하는 최적 경로 찾기"
• "이 8개 주소에 대한 배달 경로 최적화: [주소 목록]"

GPS 및 경로 매칭

• "이 GPS 추적을 정리하고 도로의 실제 경로 표시: [타임스탬프가 있는 좌표 목록]"
• "기록된 자전거 라이딩을 자전거 네트워크에 스냅: [GPS 좌표]"
• "이 운전 경로를 도로 네트워크에 매칭하고 교통 혼잡 수준 표시"

오프라인 지리공간 계산

• "이 두 좌표 사이의 거리는 마일로 얼마인가요?"
• "이 폴리곤의 면적을 제곱킬로미터로 계산"
• "37.7749°N, 122.4194°W의 지점이 이 서비스 영역 폴리곤 내부에 있나요?"
• "샌프란시스코에서 뉴욕까지의 방위각은?"
• "런던과 파리의 중간 지점 찾기"
• "이 위치 주변에 5마일 버퍼 존 생성"
• "이 동네 경계의 중심점 계산"
• "이 경로 좌표의 경계 상자는?"
• "이 복잡한 폴리곤을 단순화하여 점 수 줄이기"

더 나은 결과를 위한 팁

• 위치에 대해 구체적으로 지정(전체 주소 또는 랜드마크 이름 사용)
• 선호하는 이동 수단 지정(운전, 도보, 자전거)
• 관련된 경우 시간 제약 포함("러시아워 동안", "오후 3시에")
• 필요한 경우 특정 출력 형식 요청("지도 이미지로", "JSON 형식으로")

자세한 예제: 다양한 사용 사례와 MCP Inspector 테스트 지침이 포함된 search-along-route 프롬프트의 포괄적인 예제는 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 호출이 필요 없습니다

사용 예시: "스페이스 니들에서 북동쪽으로 10km 떨어진 지점은 어디인가요?"

방위각 도구

한 좌표에서 다른 좌표로의 나침반 방향(방위각)을 계산합니다.

기능:

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

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

중간점 도구

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

기능:

• 지구의 곡면에서 실제 중간점을 계산합니다
• 만남 장소 제안에 유용합니다
• 장거리 계산을 올바르게 처리합니다

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

중심점 도구

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

기능:

• 복잡한 모양과 함께 작동합니다
• 모든 점의 산술 평균을 반환합니다
• 라벨 또는 마커 배치에 유용합니다

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

면적 도구

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

기능:

• 여러 단위 지원: 제곱미터, 제곱킬로미터, 에이커, 헥타르, 제곱마일, 제곱피트
• 지구 표면에서 정확한 면적 계산
• 모든 크기의 폴리곤과 함께 작동합니다

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

경계 상자 도구

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

기능:

• 점, 선, 폴리곤, 멀티폴리곤과 함께 작동합니다
• [최소경도, 최소위도, 최대경도, 최대위도]를 반환합니다
• 뷰포트 계산 및 공간 인덱싱에 유용합니다

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

버퍼 도구

점, 선 또는 폴리곤 주위에 버퍼 영역(폴리곤)을 생성합니다.

기능:

• 여러 거리 단위를 지원합니다
• 점 주위에 원형 버퍼를 생성합니다
• 근접 분석 및 영향 구역 생성에 유용합니다

사용 예시: "이 위치 주변에 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를 사용하여 여러 지점 간의 이동 시간과 거리를 계산합니다. 기능은 다음과 같습니다:

• 효율적인 일대다, 다대일 또는 다대다 라우팅 계산
• 다양한 이동 프로필 지원(교통량 반영 운전, 운전, 도보, 자전거)
• 교통량 반영 계산을 위한 출발 시간 지정
• 거리 및 소요 시간 지표가 포함된 경로 요약
• 접근 방식(연석/무제한) 및 허용 출발 방위각 범위 제어

정적 이미지 도구

Mapbox 정적 이미지 API를 사용하여 정적 지도 이미지를 생성합니다. 기능은 다음과 같습니다:

• 사용자 지정 지도 스타일(거리, 야외, 위성 등)
• 조정 가능한 이미지 크기 및 확대/축소 수준
• 사용자 지정 색상 및 라벨이 있는 여러 마커 지원
• 폴리라인 및 폴리곤을 포함한 오버레이 옵션
• 지정된 좌표에 자동 맞춤

카테고리 검색 도구

Mapbox Search Box 카테고리 검색 API를 사용하여 카테고리 검색을 수행합니다. 기능은 다음과 같습니다:

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

역지오코딩 도구

Mapbox 지오코딩 V6 API를 사용하여 역지오코딩을 수행합니다. 기능은 다음과 같습니다:

• 지리적 좌표를 사람이 읽을 수 있는 주소로 변환
• 사용자 지정 가능한 세부 수준(거리, 동네, 도시 등)
• 유형별 결과 필터링(주소, 관심 지점, 동네 등)
• 여러 언어 지원
• 풍부한 위치 컨텍스트 정보

지상 위치 도구

"이 좌표 근처에 무엇이 있나요?" 질문에 단일 호출로 답변합니다 — 장소 이름, 주변 관심 지점, 이동 시간 도달 가능성 — 인용과 함께 실시간 Mapbox 데이터에서 가져옵니다. reverse_geocode_tool을 웹 검색과 연결하는 대신 이 도구를 사용하세요.

기능:

• 쿼리를 분류하고(라우팅, 동네 컨텍스트, 관심 지점 검색 또는 지역/도달 가능성) 관련 데이터만 가져옵니다
• 요청 시 카테고리별 주변 관심 지점 검색
• 이동 시간 도달 가능성 요약(등시선 기반)
• 지상 위치와 주변 관심 지점이 표시된 render_map_tool 참조를 반환합니다

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

장소 세부 정보 도구

Mapbox ID를 사용하여 특정 장소에 대한 자세한 정보를 검색합니다 — 사진, 영업 시간, 평점, 전화번호 및 웹사이트 URL. 특정 결과에 대한 자세한 정보를 얻으려면 search_and_geocode_tool, category_search_tool 또는 reverse_geocode_tool 이후에 사용하세요.

사용 예시: "첫 번째 커피숍 결과에 대해 자세히 알려주세요 — 영업 시간, 전화번호 및 웹사이트"

길찾기 도구

Mapbox Directions API를 사용하여 라우팅 길찾기를 가져옵니다. 기능은 다음과 같습니다:

• 다양한 라우팅 프로필 지원: 운전(실시간 교통량 또는 일반), 도보, 자전거
• 여러 웨이포인트에서 경로(2-25 좌표 쌍)
• 대체 경로 옵션
• 경로 주석(거리, 소요 시간, 속도, 혼잡도)
• 일정 옵션:
  • 운전 및 교통량 반영 운전 프로필에 대한 향후 출발 시간(depart_at)
  • 운전 프로필에만 해당하는 원하는 도착 시간(arrive_by)
• 프로필별 최적화:
  • 운전: 차량 크기 제약(높이, 너비, 무게)
• 라우팅 제외 옵션:
  • 일반 제외: 페리 경로, 현금 전용 통행료
  • 운전 전용 제외: 통행료, 고속도로, 비포장 도로, 터널, 국경, 주 경계
  • 사용자 지정 지점 제외(최대 50개 지리적 지점 회피)
• GeoJSON 지오메트리 출력 형식

등시선 도구

Mapbox Isochrone API를 사용하여 위치에서 지정된 시간 내에 도달할 수 있는 영역을 계산합니다. 기능은 다음과 같습니다:

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

검색 및 지오코딩 도구

Mapbox Search Box 텍스트 검색 API 엔드포인트를 사용하여 관심 지점, 주소, 장소 및 해당 API에서 지원하는 기타 모든 유형을 검색하고 지오코딩합니다. 이 도구는 이전에 ForwardGeocodeTool 및 PoiSearchTool(이 MCP 서버의 이전 버전)에서 제공되던 기능을 단일 도구로 통합합니다.

지도 매칭 도구

Mapbox Map Matching API를 사용하여 GPS 추적을 도로 네트워크에 스냅합니다. 기능은 다음과 같습니다:

• 노이즈가 있는 GPS 추적을 도로 네트워크의 깨끗한 경로로 변환
• 다양한 이동 프로필 지원(운전, 교통량 반영 운전, 도보, 자전거)
• 요청당 최대 100개 좌표 쌍 처리
• 속도 기반 정확도 향상을 위한 선택적 타임스탬프
• 다양한 GPS 품질 수준에 대한 구성 가능한 스냅 반경
• 경로 주석(속도 제한, 거리, 소요 시간, 교통 혼잡도)
• 여러 지오메트리 출력 형식(GeoJSON, 폴리라인)

사용 예시: "이 GPS 추적을 정리하고 도로에 스냅하세요: [타임스탬프가 있는 좌표]"

최적화 도구

Mapbox Optimization API를 사용하여 여러 위치를 통과하는 최적 경로를 찾습니다. 기능은 다음과 같습니다:

• 2-12개 위치에 대한 외판원 문제(TSP) 해결
• 다양한 이동 프로필 지원(운전, 교통량 반영 운전, 도보, 자전거)
• 유연한 시작 및 끝 지점 구성
• 왕복 또는 편도 여행 최적화
• 턴바이턴 내비게이션 안내(선택 사항)
• 경로 주석(거리, 소요 시간, 속도)
• 여러 지오메트리 출력 형식(GeoJSON, 폴리라인)

사용 예시: "이 5개 정류장을 방문하는 최적 경로를 찾으세요: [주소 또는 좌표 목록]"

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

개발

서버 검사

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 요청 계측
• ✅ 구성 가능한 내보내기 도구 (콘솔, OTLP)
• ✅ 보안 중심 (데이터 보호, JWT 검증)
• ✅ 프로덕션 준비 완료 (<1% CPU 오버헤드)

기여

Mapbox MCP 서버에 대한 기여를 환영합니다! 풀 리퀘스트를 제출하기 전에 CONTRIBUTING.md를 읽어주세요.

전체 표준 및 지침:

• CONTRIBUTING.md - 시작하기, PR 프로세스, 빠른 참조
• 엔지니어링 표준 (docs/engineering_standards.md) - 완전한 코드 품질, 테스트, 문서화 및 협업 표준
• Claude Code 가이드 (CLAUDE.md) - Claude Code를 사용하는 기여자를 위한 표준 및 패턴
• AI 에이전트 지침 (AGENTS.md) - 기타 AI 코딩 어시스턴트(Cursor, Continue, Aider 등)를 위한 가이드
• GitHub Copilot 지침 - GitHub Copilot을 책임감 있게 사용하기 위한 모범 사례

기여자를 위한 빠른 시작

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

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

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

Mapbox API로 전송되는 데이터

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

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

사용자의 개인정보 보호

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

제3자 데이터 사용

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

지원 및 연락처

MCP 서버 문제 관련

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

Mapbox API 질문 관련

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

유지보수 약속

이 MCP 서버는 Mapbox, Inc.에서 공식적으로 유지보수합니다. 제공 사항:

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

---

MIT 라이선스