Geospatial intelligence with Mapbox APIs like geocoding, POI search, directions, isochrones, etc.
io.github.mapbox/mcp-server (MCP Server)
The Mapbox MCP Server is a Node.js implementation of the Model Context Protocol (MCP) that provides access to Mapbox APIs for geospatial intelligence. Its scope includes Mapbox capabilities such as geocoding, POI search, directions, and isochrones, enabling AI applications to use location intelligence.
๐ ๏ธ Key Features
MCP server for Mapbox APIs
Geocoding support
POI search support
Directions support
Isochrones support
๐ Use Cases
Geospatially aware AI applications
Place understanding and reasoning
Navigation-related workflows using directions
Accessibility or area-time analysis using isochrones
โก Developer Benefits
Standard MCP interface for Mapbox API access
Uses location intelligence data from the Mapbox platform
โ ๏ธ Limitations
Available information only specifies supported Mapbox areas (geocoding, POI search, directions, isochrones); no additional tooling or configuration details are provided in the source excerpt.
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
Mapbox MCP Server Demo
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:
Smolagents Integration - Example showing how to connect Smolagents AI agents to Mapbox's tools
Importing Tools Directly - Use Mapbox tools in your own applications without running the MCP server
render_map_tool Guide - The map visualization primitive: full payload schema and how to render your own data standalone, without any other Mapbox tool
Elicitations - 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:
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 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:
bash
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)
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 Haversine formula.
Features:
Supports multiple units: kilometers, miles, meters, feet, nautical miles
Accurate great-circle distance calculation
No API calls required
Example Usage: "What's the distance between San Francisco (37.7749ยฐN, 122.4194ยฐW) and New York (40.7128ยฐN, 74.0060ยฐW)?"
Points Within Polygon Tool
Test one or more points against a polygon or multipolygon, returning only those inside. Handles a single point or a batch in one call.
Features:
Works with complex polygons including holes
Supports multipolygons
Batch-tests any number of points in one call
Useful for geofencing, delivery zone validation, and customer segmentation
Example Usage: "Which of these delivery addresses are inside our service area?"
Destination Tool
Calculate a destination point given a starting point, bearing, and distance using geodesic (great-circle) offset.
Features:
Straight-line offset, not a routed path
Useful for "find a point 5km north of X" or constructing search offsets
No API calls required
Example Usage: "What's the point 10km northeast of the Space Needle?"
Bearing Tool
Calculate the compass direction (bearing) from one coordinate to another.
Features:
Returns bearing in degrees (0-360ยฐ)
Provides cardinal direction (N, NE, E, SE, S, SW, W, NW)
Useful for navigation and directional queries
Example Usage: "What direction should I head to go from here to the airport?"
Midpoint Tool
Find the geographic midpoint between two coordinates along the great circle path.
Features:
Calculates true midpoint on Earth's curved surface
Useful for meeting point suggestions
Handles long-distance calculations correctly
Example Usage: "What's halfway between San Francisco and New York?"
Centroid Tool
Calculate the geometric center (centroid) of a polygon or multipolygon.
Features:
Works with complex shapes
Returns arithmetic mean of all points
Useful for placing labels or markers
Example Usage: "Where should I place a marker for this neighborhood boundary?"
Useful for viewport calculations and spatial indexing
Example Usage: "What's the bounding box for this route?"
Buffer Tool
Create a buffer zone (polygon) around a point, line, or polygon.
Features:
Supports multiple distance units
Creates circular buffers around points
Useful for proximity analysis and creating zones of influence
Example Usage: "Show me a 5km buffer zone around this location"
Simplify Tool
Reduce the number of vertices in a line or polygon using the Douglas-Peucker algorithm.
Features:
Configurable tolerance for detail level
Preserves overall shape while reducing complexity
Useful for reducing file sizes and improving rendering performance
Option to maintain topology (prevent self-intersections)
Example Usage: "Simplify this complex boundary to reduce the number of points"
Length Tool
Measure the total length of a line defined by a series of coordinates.
Features:
Supports kilometers, miles, meters, and feet
Useful for measuring a drawn route, path, or boundary without a routing API call
Example Usage: "How long is this hiking trail?"
Convex Tool
Compute the convex hull of a set of points โ the smallest convex polygon containing all of them.
Features:
Useful for bounding-area analysis or estimating coverage area
Works offline without API calls
Example Usage: "What's the smallest polygon that contains all of these store locations?"
Nearest Point Tool
Find the nearest point in a collection to a given target point.
Features:
More efficient than calling distance_tool for each candidate and sorting
Useful for finding the closest store, stop, or landmark to a location
Example Usage: "Which of these stores is closest to my current location?"
Nearest Point on Line Tool
Snap a point to the nearest position on a line or route, returning that point and the distance to it.
Features:
Useful for "which point on this route is closest to my location?" or map-matching without an API call
Example Usage: "Where on this hiking trail am I closest to right now?"
Union, Intersect, and Difference Tools
Combine or compare two or more polygons โ union_tool merges them into one geometry, intersect_tool finds the area they share, and difference_tool subtracts one from another.
Features:
Useful for combining service areas, finding coverage overlap, or computing exclusion zones (e.g. "what's covered by zone A but not zone B?")
Works entirely offline โ no API calls required
Each returns a render_map_tool reference so the result can be visualized directly
Example Usage: "Combine these two delivery zones into one coverage area" / "Where do these two isochrones overlap?" / "What part of this service area isn't covered by our 15-minute isochrone?"
Mapbox API Tools
Category List Tool (Deprecated)
โ ๏ธ Deprecated: Use the resource_reader_tool with URI mapbox://categories instead, or access the mapbox://categories resource directly if your client supports MCP resources.
This tool is maintained for backward compatibility with clients that don't support MCP resources or the resource_reader_tool.
Matrix Tool
Calculates travel times and distances between multiple points using Mapbox Matrix API. Features include:
Efficient one-to-many, many-to-one or many-to-many routing calculations
Support for different travel profiles (driving-traffic, driving, walking, cycling)
Departure time specification for traffic-aware calculations
Route summarization with distance and duration metrics
Control approach (curb/unrestricted) and range of allowed departure bearings
Convert geographic coordinates to human-readable addresses
Customizable levels of detail (street, neighborhood, city, etc.)
Results filtering by type (address, poi, neighborhood, etc.)
Support for multiple languages
Rich location context information
Ground location tool
Answers "what's near this coordinate" questions in a single call โ place name, nearby points of interest, and travel-time reachability โ sourced from live Mapbox data with citations. Use this instead of chaining reverse_geocode_tool with a web search.
Features:
Classifies the query (routing, neighborhood context, POI search, or region/reachability) and fetches only the relevant data
Returns a render_map_tool reference with the grounded location and nearby POIs plotted
Example Usage: "What neighborhood is this coordinate in, and are there any coffee shops nearby?"
Place details tool
Retrieves detailed information about a specific place using its Mapbox ID โ photos, opening hours, ratings, phone numbers, and website URLs. Use after search_and_geocode_tool, category_search_tool, or reverse_geocode_tool to get more detail on a specific result.
Example Usage: "Tell me more about that first coffee shop result โ hours, phone number, and website"
Uses the Mapbox Search Box Text Search API endpoint to power searching for and geocoding POIs, addresses, places, and any other types supported by that API.
This tool consolidates the functionality that was previously provided by the ForwardGeocodeTool and PoiSearchTool (from earlier versions of this MCP server) into a single tool.
Example Usage: "Find the optimal route to visit these 5 stops: [list of addresses or coordinates]"
Note: A V2 API with advanced features (time windows, capacity constraints, multiple vehicles) is available but requires beta access. The V2 implementation is included in the codebase but not registered by default.
Feedback tool
Sends a user's feedback about the app or agent to its developer, through the Mapbox Feedback API (Public Preview). It's filed under the account that owns the access token, so when you build an app or agent on this server with your own token, your users' feedback lands in the same feed as your apps' Feedback Agent reports, and you review it in Feedback Explorer. It does not report problems to Mapbox. Like Feedback Agent, it's for anything about your product that helps you understand what users need, for example:
A place that has closed, has wrong details, or sits on the wrong spot
A place or address that can't be found
A closed road, a wrong speed limit, or traffic shown wrong
A route with an illegal turn or entrance, or no route at all
Something about the app itself, such as a bug or a suggestion (application_issue)
It sends the feedback text, a category and the location, and returns the item's id and status. The location is optional, for feedback that isn't about a place; the API requires one, so the tool sends 0, 0, as the Feedback API team recommends for now. Nothing is sent without the user's go-ahead: clients that support elicitation show a confirmation prompt first, and the tool description asks the model to confirm in chat everywhere else.
The Feedback API is free during Public Preview. At General Availability, Feedback Agent charges $0.02 per feedback item. To avoid filing the same problem twice, before sending the tool checks the account's own reports from the last 30 days. If one in the same category within 50 m is still awaiting review (feedback without a location isn't checked), it returns that report instead of sending a new one. The Feedback API only lists the account's own reports, so this can't catch reports from other accounts. send_anyway: true skips the check when the user says theirs is a different problem.
Requirements: the access token needs the user-feedback:write scope to send, and user-feedback:read for the duplicate check. Without the write scope the tool returns an error saying so. Without the read scope it sends without checking and says so in its result. To leave the tool out, start the server with --disable-tools feedback_tool.
Example Usage: "Blue Bottle on Mint St closed last year, can you send that as feedback?"
Report tool
Sends feedback about the Mapbox MCP server itself to the Mapbox team that builds it: a bug, a tool that gave a wrong or confusing result, a missing capability or a suggestion. It's filed under Mapbox's own account, not yours, so it needs no extra token scope, and it can't be read back or withdrawn afterward. It isn't for reporting wrong map, place or routing data.
The server adds its version, the client's name and version, and the tool the feedback is about to the end of the text. Nothing is sent without the user's go-ahead: clients that support elicitation show a confirmation prompt first, and the tool description asks the model to confirm in chat everywhere else.
It uses the endpoint the Feedback API team added for the Mapbox CLI's mapbox report command. To leave the tool out, start the server with --disable-tools report_tool.
Example Usage: "The map didn't draw any of my isochrones. Can you let the Mapbox MCP team know?"
List public tokens tool
Lists the account's public (pk.) access tokens, for an agent building a web page or app outside the chat that loads Mapbox GL JS or calls Mapbox APIs from the browser. In the chat, render_map_tool needs no token. Each token comes with its name, whether it's the default, its URL restrictions and its scopes.
Pass site_url (where the page will run) and the tool recommends a token restricted to that URL when the account has one. Otherwise it recommends the default public token and says that a published site should use a URL-restricted token instead, with a link to create one. Anyone who copies an unrestricted public token can use it, and the usage bills to the account.
It never returns secret or temporary tokens, and it can't create tokens (that needs tokens:write; the DevKit server's create_token_tool does it).
Requirements: listing needs the tokens:read scope, the same one the in-chat map already uses to find the default public token. With a pk. access token, or when listing fails on the server's own MAPBOX_ACCESS_TOKEN and MAPBOX_PUBLIC_TOKEN is set, it returns that token instead. A caller with its own bearer token (the hosted server) never gets MAPBOX_PUBLIC_TOKEN, and a token restricted to other URLs is never recommended. To leave the tool out, start the server with --disable-tools list_public_tokens_tool.
Example Usage: "Build me a single-page site that shows our three store locations on a Mapbox map."
Development
Inspecting server
Using Node.js
sh
# Run the built image
npm run inspect:build
Using Docker
sh
# 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
Create new tool
sh
npx plop create-tool
# provide tool name without suffix (e.g. Search)
Releasing a New Version
sh
# 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
Important: The publisher workflow validates that package.json and server.json versions match the release version. Skipping the version bump or manifest sync will cause publish failures.
OpenTelemetry Tracing
This MCP server includes comprehensive OpenTelemetry tracing for production observability:
Quick Demo
sh
# 1. Copy the example configurationcp .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
Note: The server automatically loads configuration from your .env file at startup. The .env.example file includes configuration examples for multiple observability platforms.
Supported Observability Platforms
Configuration examples included in .env.example for:
Cloud Providers:
โ๏ธ AWS X-Ray
โ๏ธ Azure Monitor (Application Insights)
โ๏ธ Google Cloud Trace
SaaS Platforms:
๐ Datadog
๐ New Relic
๐ Honeycomb
๐ Any OTLP-compatible backend
Production Configuration
See docs/tracing.md for complete setup instructions including: