Mapbox MCP

Mapbox MCP Server

Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs.

Unlock Geospatial Intelligence for Your AI Applications

The Mapbox MCP Server transforms any AI agent or application into a geospatially-aware system by providing seamless access to Mapbox's comprehensive location intelligence platform. With this server, your AI can understand and reason about places, navigate the physical world, and access rich geospatial data including:

• Global geocoding to convert addresses and place names to coordinates and vice versa
• Points of interest (POI) search across millions of businesses, landmarks, and places worldwide
• Multi-modal routing for driving, walking, and cycling with real-time traffic
• Travel time matrices to analyze accessibility and optimize logistics
• Route optimization to find the optimal visiting order for multiple stops (traveling salesman problem)
• Map matching to snap GPS traces to the road network for clean route visualization
• Isochrone generation to visualize areas reachable within specific time or distance constraints
• Live, interactive map rendering (render_map_tool) to display routes, search results, and your own custom GeoJSON on a real Mapbox GL JS map directly inside the chat
• Static map images to create visual representations of locations, routes, and geographic data
• Offline geospatial calculations for distance, area, bearing, buffers, and spatial analysis without requiring API calls

Whether you're building an AI travel assistant, logistics optimizer, location-based recommender, or any application that needs to understand "where", the Mapbox MCP Server provides the spatial intelligence to make it possible. You can also enable it on popular clients like Claude Desktop and VS Code. See below for details

Usage

A Mapbox access token is required to use this MCP server.

Hosted MCP Endpoint

For quick access, you can use our hosted MCP endpoint:

Endpoint: https://mcp.mapbox.com/mcp

For detailed setup instructions for different clients and API usage, see the Hosted MCP Server Guide.

To get a Mapbox access token:

1. Sign up for a free Mapbox account at mapbox.com/signup
2. Navigate to your Account page
3. Create a new token or use the default public token

For more information about Mapbox access tokens, see the Mapbox documentation on access tokens.

Integration Guides

For detailed setup instructions for different integrations, refer to the following guides:

• Claude Desktop Setup - Instructions for configuring Claude Desktop to work with this MCP server
• Goose Setup - Setting up Goose AI agent framework
• VS Code Setup - Setting up a development environment in Visual Studio Code
• Cursor AI IDE Setup - Setting up a development environment in Cursor AI IDE
• Smolagents Integration - Example showing how to connect Smolagents AI agents to Mapbox's tools
• [Importing Tools Directly](./docs/importing-tools.md) - Use Mapbox tools in your own applications without running the MCP server
• [`render_map_tool` Guide](./docs/render-map-tool.md) - The map visualization primitive: full payload schema and how to render your own data standalone, without any other Mapbox tool
• [Elicitations](./docs/elicitations.md) - How search_and_geocode_tool and directions_tool ask the user to disambiguate results or pick a route, and how they fall back gracefully when the client doesn't support it

Example Prompts

Try these prompts with Claude Desktop or other MCP clients after setup:

Location Grounding

For coordinate-first queries — _"what's near me"_, _"what neighborhood is this"_, _"what's reachable in N minutes"_ — use ground_location_tool. It composes reverse geocoding, category search, and isochrone in a single call, adaptively choosing the right strategy based on the query, and returns typed records (names, addresses, coordinates, distances, reachability polygons) with citations.

Each of the four prompts below exercises a different strategy in one tool call:

• Neighborhood — _"What neighborhood is 47.6097, -122.3408, and what's around me?"_
• POI — _"Coffee shops within a 10-minute walk of 40.7580, -73.9855"_
• Region — _"What can I reach in a 15-minute walk from 37.7749, -122.4194?"_
• Routing — _"Closest routable point to drop someone off at 34.0522, -118.2437"_

Location Discovery

• "Find coffee shops within walking distance of the Empire State Building"
• "I want to go from Seattle to Portland, is there a Starbucks along the way?"
• "Show me gas stations along the route from Boston to New York"
• "What restaurants are near Times Square?"

Navigation & Travel

• "Get driving directions from LAX to Hollywood with current traffic"
• "How long would it take to walk from Central Park to Times Square?"
• "Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi during rush hour"

Visualization & Maps

• "Using the Mapbox map render tool, show me directions from the Golden Gate Bridge to Union Square in San Francisco" — renders a live, interactive route on a real Mapbox map
• "Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf with markers at both locations"
• "Show me a satellite view of Manhattan with key landmarks marked"
• "Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"
• "Show a fill polygon over these coordinates: [...], with a marker labeled 'Warehouse' at [...]" — renders your own GeoJSON directly via render_map_tool, no other Mapbox tool needed

Analysis & Planning

• "Show me areas reachable within 30 minutes of downtown Portland by car"
• "Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
• "Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
• "Optimize a delivery route for these 8 addresses: [list of addresses]"

GPS & Route Matching

• "Clean up this GPS trace and show the actual route on roads: [list of coordinates with timestamps]"
• "Snap this recorded bicycle ride to the cycling network: [GPS coordinates]"
• "Match this driving route to the road network and show traffic congestion levels"

Offline Geospatial Calculations

• "What's the distance in miles between these two coordinates?"
• "Calculate the area of this polygon in square kilometers"
• "Is the point at 37.7749°N, 122.4194°W inside this service area polygon?"
• "What's the bearing from San Francisco to New York?"
• "Find the midpoint between London and Paris"
• "Create a 5-mile buffer zone around this location"
• "Calculate the centroid of this neighborhood boundary"
• "What's the bounding box for these route coordinates?"
• "Simplify this complex polygon to reduce the number of points"

Tips for Better Results

• Be specific about locations (use full addresses or landmark names)
• Specify your preferred travel method (driving, walking, cycling)
• Include time constraints when relevant ("during rush hour", "at 3 PM")
• Ask for specific output formats when needed ("as a map image", "in JSON format")

Detailed examples: See examples/search-along-route.md for comprehensive examples of the search-along-route prompt with different use cases and MCP Inspector testing instructions.

Resources

The MCP server exposes static reference data as MCP resources. Resources provide read-only access to data that clients can reference directly without making tool calls.

Available Resources

Mapbox Categories Resource

URI Pattern: mapbox://categories or mapbox://categories/{language}

Access the complete list of available category IDs for use with the category search tool. Categories can be used to filter search results by type (e.g., "restaurant", "hotel", "gas_station").

Examples:

• mapbox://categories - Default (English) category list
• mapbox://categories/ja - Japanese category names
• mapbox://categories/es - Spanish category names

Accessing Resources:

• Clients with native MCP resource support: Use the resources/read MCP protocol method
• Clients without resource support: Use the resource_reader_tool with the resource URI

Rich Map Previews (render_map_tool)

Every geospatial tool in this server (directions, isochrone, search, and more) can display its result as a live, interactive Mapbox GL JS map via `render_map_tool` — the server's single visualization primitive. It renders through the MCP Apps protocol (@modelcontextprotocol/ext-apps) as a self-contained HTML panel directly inside the chat, with a Fullscreen toggle, in supported clients:

• Claude Desktop ✅
• VS Code with GitHub Copilot ✅
• Claude Code ✅
• [Goose](https://github.com/block/goose) ✅

You don't need any of this server's other tools to use it. render_map_tool also accepts hand-composed GeoJSON directly — your own polygons, markers, and routes — with no dependency on directions_tool, isochrone_tool, or any other Mapbox API call. See [the full `render_map_tool` guide](./docs/render-map-tool.md) for the payload schema and a complete standalone example.

If you need a guaranteed static image in clients without MCP Apps support, use static_map_image_tool instead — it returns a base64-encoded PNG/JPEG that every client can display.

CLIENT_NEEDS_RESOURCE_FALLBACK

Resource Fallback Tools (Opt-In for Non-Compliant Clients)

Resources are a core MCP feature supported by most clients (Claude Desktop, VS Code, MCP Inspector, etc.). However, some clients (like smolagents) don't support resources at all. For these clients, the server can provide "resource fallback tools" that deliver the same content as resources but via tool calls.

Fallback Tools:

• resource_reader_tool - Generic fallback for reading any resource by URI
• category_list_tool - Provides access to category list (mapbox://categories)

By default, these tools are NOT included (assumes your client supports resources). If your client doesn't support resources, enable the fallback tools:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

When to set this:

• ✅ Set to true if using smolagents or other clients without resource support
• ❌ Leave unset (default) if using Claude Desktop, VS Code, MCP Inspector, or any resource-capable client
• ❌ Leave unset if unsure (most clients support resources)

Tools

Utility Tools

Resource Reader Tool

Provides access to MCP resources for clients that don't support the native MCP resource API. Use this tool to read resources like the category list.

Parameters:

• uri: The resource URI to read (e.g., mapbox://categories, mapbox://categories/ja)

Example Usage:

• Read default categories: {"uri": "mapbox://categories"}
• Read Japanese categories: {"uri": "mapbox://categories/ja"}

Note: If your MCP client supports native resources, prefer using the resource API directly for better performance.

Offline Geospatial Tools

These tools perform geospatial calculations completely offline without requiring Mapbox API calls. They use Turf.js for accurate geographic computations and work anywhere, even without internet connectivity.

Distance Tool

Calculate the distance between two geographic coordinates using the Haversi