사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-mcp-runtime-patterns시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Mapbox MCP Runtime Patterns
This skill provides patterns for integrating the Mapbox MCP Server into AI applications for production use with geospatial capabilities.
What is Mapbox MCP Server?
The Mapbox MCP Server is a Model Context Protocol (MCP) server that provides AI agents with geospatial tools:
Offline Tools (Turf.js):
- Distance, bearing, midpoint calculations
- Point-in-polygon tests
- Area, buffer, centroid operations
- Bounding box, geometry simplification
- No API calls, instant results
Mapbox API Tools:
- Directions and routing
- Reverse geocoding
- POI category search
- Isochrones (reachability)
- Travel time matrices
- Static map images
- GPS trace map matching
- Multi-stop route optimization
Utility Tools:
- Server version info
- POI category list
Key benefit: Give your AI application geospatial superpowers without manually integrating multiple APIs.
Understanding Tool Categories
Before integrating, understand the key distinctions between tools to help your LLM choose correctly:
Distance: "As the Crow Flies" vs "Along Roads"
Straight-line distance (offline, instant):
- Tools:
distance_tool,bearing_tool,midpoint_tool - Use for: Proximity checks, "how far away is X?", comparing distances
- Example: "Is this restaurant within 2 miles?" →
distance_tool
Route distance (API, traffic-aware):
- Tools:
directions_tool,matrix_tool - Use for: Navigation, drive time, "how long to drive?"
- Example: "How long to drive there?" →
directions_tool
Search: Type vs Specific Place
Category/type search:
- Tool:
category_search_tool - Use for: "Find coffee shops", "restaurants nearby", browsing by type
- Example: "What hotels are near me?" →
category_search_tool
Specific place/address:
- Tool:
search_and_geocode_tool,reverse_geocode_tool - Use for: Named places, street addresses, landmarks
- Example: "Find 123 Main Street" →
search_and_geocode_tool
Travel Time: Area vs Route
Reachable area (what's within reach):
- Tool:
isochrone_tool - Returns: GeoJSON polygon of everywhere reachable
- Example: "What can I reach in 15 minutes?" →
isochrone_tool
Specific route (how to get there):
- Tool:
directions_tool - Returns: Turn-by-turn directions to one destination
- Example: "How do I get to the airport?" →
directions_tool
Cost & Performance
Offline tools (free, instant):
- No API calls, no token usage
- Use whenever real-time data not needed
- Examples:
distance_tool,point_in_polygon_tool,area_tool
API tools (requires token, counts against usage):
- Real-time traffic, live POI data, current conditions
- Use when accuracy and freshness matter
- Examples:
directions_tool,category_search_tool,isochrone_tool
Best practice: Prefer offline tools when possible, use API tools when you need real-time data or routing.
Installation & Setup
Option 1: Hosted Server (Recommended)
Easiest integration - Use Mapbox's hosted MCP server at:
https://mcp.mapbox.com/mcpNo installation required. Simply pass your Mapbox access token in the Authorization header.
Benefits:
- No server management
- Always up-to-date
- Production-ready
- Lower latency (Mapbox infrastructure)
Authentication:
Use token-based authentication (standard for programmatic access):
Authorization: Bearer your_mapbox_tokenNote: The hosted server also supports OAuth, but that's primarily for interactive flows (coding assistants, not production apps).
Option 2: Self-Hosted
For custom deployments or development:
npm install @mapbox/mcp-serverOr use directly via npx:
npx @mapbox/mcp-serverEnvironment setup:
export MAPBOX_ACCESS_TOKEN="your_token_here"Reference Files
Detailed integration patterns and production guidance are organized into reference files. Load the ones relevant to your task.
- Pydantic AI -- Type-safe Python agents
Load: references/pydantic-ai.md
- CrewAI -- Multi-agent orchestration
Load: references/crewai.md
- Smolagents -- Lightweight HuggingFace agents
Load: references/smolagents.md
- Mastra -- Multi-agent TypeScript systems
Load: references/mastra.md
- LangChain -- Conversational AI with tool chaining
Load: references/langchain.md
- Custom Agent -- Zillow/TripAdvisor/DoorDash-style patterns, architecture diagrams, hybrid approach
Load: references/custom-agent.md
- Use Cases -- Real Estate, Food Delivery, Travel Planning examples
Load: references/use-cases.md
- Production Patterns -- Caching, batch operations, tool descriptions, error handling, security, rate limiting, testing
Load: references/production.md
Resources
When to Use This Skill
Invoke this skill when:
- Integrating Mapbox MCP Server into AI applications
- Building AI agents with geospatial capabilities
- Architecting Zillow/TripAdvisor/DoorDash-style apps with AI
- Choosing between MCP, direct APIs, or SDKs
- Optimizing geospatial operations in production
- Implementing error handling for geospatial AI features
- Testing AI applications with geospatial tools



