Mapbox MCP Server
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAPBOX_ACCESS_TOKEN | Yes | A Mapbox access token is required. Obtain from Mapbox account page. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
To show anything on a map, use render_map_tool: it renders an interactive Mapbox GL JS map inline. When a tool result includes mapboxRender.ref, pass that ref unchanged in render_map_tool payload_refs (several refs can share one map). Never write or edit a ref by hand. In ChatGPT Desktop, a Mapbox map stays open next to the chat and provides these tools: redraw_map (same arguments as render_map_tool), search_map, add_places, move_map, read_map. Use them to change the open map ("show coffee shops on it", "add the route"): render_map_tool would open a second map. Use static_map_image_tool only when the user explicitly asks for a static image file (PNG/JPEG), never as the default way to show a map. When building a web page or app outside this chat that needs a Mapbox token, call list_public_tokens_tool and put the pk. token it returns in the page. Public tokens are made to ship in browser code, so don't leave a placeholder like YOUR_MAPBOX_TOKEN or ask the user to paste one.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
| completions | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_public_tokens_toolA | Lists the Mapbox account's public (pk.) access tokens, for when you build a web page or app outside this chat that loads Mapbox GL JS or calls Mapbox APIs from the browser. Put the returned pk. token in the page: public tokens are made to ship in browser code, so a placeholder or asking the user to paste a token is not needed. To show a map in the chat, use render_map_tool instead; it needs no token. Pass site_url (where the page will run) to get a token restricted to that URL when the account has one. Returns each token's name, whether it is the default, its URL restrictions and scopes, a recommended token, and guidance: for a published site, use a URL-restricted token, and tell the user the default token can be reused by anyone who copies it. Secret tokens are never listed. |
| elevation_toolA | Gets ground elevation from Mapbox terrain data. Give it places ( |
| feedback_toolA | Send the user's feedback about this app or agent to its developer, through the Mapbox Feedback API (Public Preview), so the developer can understand what users need and improve the product. Feedback can be about anything in the product: for example a place that has closed or has wrong details, a missing place, a closed road, a route with an illegal turn, a wrong travel time, or something about the app itself. It is filed under the Mapbox account that owns the access token, in the same feed as that account's Feedback Agent reports, and the developer reviews it in Feedback Explorer. It does not report the problem to Mapbox. Use it only when the user asks to send feedback, or agrees when you offer. Before calling it, show the user the exact feedback text, category and location you will send and get their go-ahead. Take the coordinates from an earlier search, place or directions result rather than guessing, and leave them out when the feedback is not about a place, such as most feedback about the app itself. Send one report per problem, and do not resend one that already succeeded. To avoid filing the same problem twice, the tool first checks the account's own reports from the last 30 days and does not send if one with the same category within 50 m is still awaiting review; it returns that report instead. Only set send_anyway when the user says the earlier report is about a different problem. Returns the item id and its status (received). |
| report_toolA | Send feedback about the Mapbox MCP server to the Mapbox team that builds it: a bug, a tool that failed or gave a wrong or confusing result, a missing capability or a suggestion. It goes to Mapbox, not to the user's account, needs no special token scope, and cannot be read back or withdrawn afterward. It is for feedback about this server, not for reporting wrong map, place or routing data. Use it only when the user asks to send feedback, or agrees when you offer. Before calling it, show the user the exact text you will send and get their go-ahead. Leave out personal details the user did not ask to share. The server adds its own version and the client name. Send one report per problem, and do not resend one that already succeeded. Returns the report id. |
| ground_location_toolA | Answer questions about what is near a location, what neighborhood a coordinate is in, or what places are within walking/driving distance. Use this when given coordinates and asked about nearby places, neighborhood context, local discovery, or area summaries. It already includes reverse geocoding, so a separate reverse_geocode_tool call is not needed for the same coordinate. Pass the place category (e.g. "restaurant", "coffee", "park") as the query parameter to get nearby POIs in the same call. Returns place name, nearby POIs matching the query, and travel-time reachability — all sourced from live Mapbox data with citations. Use |
| points_within_polygon_toolA | Test one or more geographic points against a polygon, returning only those inside. Handles a single point or a batch of points in one call. Useful for delivery zone validation, fleet geofencing, and customer segmentation. Works offline without API calls. |
| union_toolA | Merge two or more polygons into a single unified geometry. Useful for combining service areas, delivery zones, isochrones, or coverage regions. Returns a Polygon or MultiPolygon if the inputs do not overlap. Works offline without API calls. INPUT SHAPE: pass |
| nearest_point_toolA | Find the nearest point in a collection to a given target point. More efficient than calling distance_tool for each candidate and sorting. Useful for finding the closest store, stop, or landmark to a location. Works offline without API calls. |
| intersect_toolA | Find the intersection geometry of two polygons — the area they share in common. Useful for coverage overlap analysis, finding shared service areas, or zone overlap. Returns null geometry if the polygons do not overlap. Works offline without API calls. INPUT SHAPE: |
| difference_toolA | Subtract one polygon from another, returning the area in polygon1 that is not covered by polygon2. Useful for computing exclusion zones, finding uncovered service areas, or "what is in zone A but not zone B?". Returns null geometry if polygon2 fully covers polygon1. Works offline without API calls. INPUT SHAPE: |
| destination_toolA | Calculate a destination point given a starting point, bearing, and distance using geodesic (great-circle) straight-line offset. Useful for "find a point 5km north of X", constructing search offsets, or computing waypoints. Bearing: 0=north, 90=east, 180/-180=south, -90=west. Note: this calculates a straight-line geographic offset, not road-network distance. Works offline without API calls. |
| length_toolA | Measure the total length of a line defined by a series of coordinates. Useful for measuring a drawn route, path, or boundary without a routing API call. Supports kilometers, miles, meters, and feet. Works offline without API calls. |
| nearest_point_on_line_toolA | Snap a point to the nearest position on a line or route. Returns the closest point on the line and the distance to it. Useful for "which point on this route is closest to my location?" or map-matching without the API. Works offline without API calls. |
| convex_toolA | Compute the convex hull of a set of points — the smallest convex polygon that contains all the points. Useful for bounding area analysis, estimating coverage area, or wrapping a set of locations. Works offline without API calls. |
| place_details_toolA | Retrieve detailed information about a specific place using its Mapbox ID. Use after search_and_geocode_tool, category_search_tool, or reverse_geocode_tool to get additional details such as photos, opening hours, phone numbers, and website URLs. Requires the mapbox_id field from a previous search result. Primarily covers points of interest (businesses, addresses, buildings); mapbox_ids for neighborhoods, cities, or other administrative boundaries are also supported but return more limited data (name, address, coordinates — no photos, hours, or contact info). The primary POI lookup is Public Preview with a default quota of 1,000 requests/month; contact Mapbox if you need a higher volume. |
| simplify_toolA | Simplify a LineString or Polygon by reducing the number of vertices while preserving the general shape. Uses the Douglas-Peucker algorithm. Useful for reducing file sizes and improving rendering performance. Works offline without API calls. |
| bbox_toolA | Calculate the bounding box (extent) of any geometry. Returns the minimum and maximum longitude and latitude that encompass the geometry. Works offline without API calls. |
| centroid_toolB | Calculate the geometric center (centroid) of a polygon or multipolygon. The centroid is the arithmetic mean position of all points in the shape. Works offline without API calls. |
| midpoint_toolA | Calculate the geographic midpoint between two coordinates. Returns the point that is halfway between the two input points along the great circle path. Works offline without API calls. |
| bearing_toolA | Calculate the bearing (compass direction) from one point to another. Returns bearing in degrees where 0° is North, 90° is East, 180° is South, and 270° is West. Works offline without API calls. |
| area_toolB | Calculate the area of a polygon or multipolygon. Supports various units including square meters, kilometers, acres, and hectares. Works offline without API calls. |
| buffer_toolA | Create a buffer zone (polygon) around a point, line, or polygon at a specified distance. Useful for proximity analysis, service areas, or creating zones of influence. Works offline without API calls. |
| distance_toolA | Calculate the distance between two geographic coordinates. Supports various units including kilometers, miles, meters, feet, and nautical miles. Uses the Haversine formula for accurate great-circle distance calculations. This tool works offline without requiring API calls. |
| category_search_toolA | Return all places that match a category (industry, amenity, or NAICS‑style code). Use when the user asks for a type of place, plural or generic terms like 'museums', 'coffee shops', 'electric‑vehicle chargers', or when the query includes is‑a phrases such as 'any', 'all', 'nearby'. Do not use when a unique name or brand is provided. Supports both JSON and text output formats. |
| directions_toolA | Fetches directions from Mapbox API based on provided coordinates and direction method. Returns a |
| isochrone_toolA | Computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of Polygons or LineStrings in GeoJSON format that you can display on a map. Common use cases: - Show a user how far they can travel in X minutes from their current location - Determine whether a destination is within a certain travel time threshold - Compare travel ranges for different modes of transportation' |
| map_matching_toolA | Snap a recorded GPS trace to roads using Mapbox Map Matching API. Takes a dense, noisy coordinate sequence (2-100 points, recorded seconds or tens of meters apart) and returns a clean route aligned with actual roads, bike paths, or walkways. Useful for analyzing recorded trips, cleaning fleet tracking data, or processing fitness activity traces. Not for routing between a few places or addresses: points kilometers apart fail to match, so use directions_tool for that. Returns confidence scores, matched geometry, and optional traffic/speed annotations. |
| matrix_toolA | Calculates travel times and distances between multiple points using Mapbox Matrix API. Put all the points in one call (up to 25, 10 for driving-traffic) rather than one call per pair: the API allows 60 requests per minute (30 for driving-traffic). |
| optimization_toolA | Find the optimal (shortest by travel time) route through a set of 2-12 coordinates. Solves the Traveling Salesman Problem to determine the best visiting order. Supports options for starting point, ending point, and whether to return to start. |
| render_map_toolA | Display a live, interactive Mapbox GL JS map. Use this when someone wants to see a location, route, or dataset on a map. In ChatGPT Desktop the map stays open next to the chat and provides its own tools (redraw_map, which takes the same arguments as this tool, search_map, add_places, move_map, read_map): use them to change that map, because another call to this tool opens a second map. Preferred usage: any other Mapbox tool returns a |
| reverse_geocode_toolA | Convert geographic coordinates (longitude, latitude) into a human-readable address or place name. Use only when you need an address/place name alone. If you also need nearby places, neighborhood context, or travel-time reachability, use ground_location_tool instead — it already includes reverse geocoding plus POI search and isochrone in one call. This tool cannot reverse geocode businesses, landmarks, or POIs. Supports JSON and text output formats. |
| static_map_image_toolA | Generates a static map image from Mapbox Static Images API. Supports center coordinates, zoom level (0-22), image size (up to 1280x1280), various Mapbox styles, and overlays (markers, paths, GeoJSON). Returns PNG for vector styles, JPEG for raster-only styles. Use only when the user explicitly asks for a static image file — to show a map, use render_map_tool instead, which renders an interactive map. |
| search_and_geocode_toolA | Search for POIs, brands, chains, geocode cities, towns, addresses. Do not use for generic place types such as 'museums', 'coffee shops', 'tacos', etc, because category_search_tool is better for that. Setting a proximity point is strongly encouraged for more local results. The underlying Search Box API is rolling out natural-language query understanding (e.g. 'quiet coffee shops with wifi near downtown'), so richer free-text phrasing in |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| find-places-nearby | Helps you search for specific types of places near a location with optional map visualization |
| get-directions | Provides turn-by-turn directions between two locations with options for different travel modes |
| search-along-route | Finds specific types of places along a route between two locations, using buffer analysis and POI search |
| show-reachable-areas | Visualizes areas that can be reached from a location within a specified time using isochrones |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Mapbox Map App UI | Generic Mapbox GL JS renderer driven by render_map_tool payloads (MCP Apps) |
| Mapbox Static Map Viewer | Shows the static_map_image_tool image at full width (MCP Apps) |
| Mapbox Categories | List of all available Mapbox Search API categories. Categories can be used for filtering search results. Supports localization via language parameter in URI (e.g., mapbox://categories/ja for Japanese). A language code the API does not support gets the default (English) list. |
| Mapbox MCP Server Version | Version information for the Mapbox MCP server, including version number, git SHA, tag, and branch. |
TDQS
Scored across 33 tools
Most tools have clearly distinct operations, and the descriptions actively clarify boundaries between overlapping areas such as render_map_tool vs static_map_image_tool, ground_location_tool vs reverse_geocode_tool, and directions_tool vs map_matching_tool. A few geometry utilities and search/location tools could still be confused at a glance, but the descriptions usually resolve the ambiguity.
All tools follow a consistent snake_case naming convention with a uniform `_tool` suffix. The names are descriptive and predictable, even though some are verb-first and others noun-first.
With 33 tools, the surface is heavy for a single MCP server and exceeds the typical well-scoped range. While many tools are individually justified by Mapbox's broad domain, the large number increases selection burden and makes the set harder to navigate.
The surface covers a wide range of Mapbox capabilities: geocoding, category search, place details, routing, isochrones, matrices, optimization, map matching, elevation, static and interactive rendering, feedback, token listing, and offline geometry operations. There are minor gaps, such as style listing or more advanced token management, but core workflows are well covered.