Skip to content
Back to search

mcp-server

Mapbox Model Context Protocol (MCP) server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mapbox/mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mapbox/mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mapbox--mcp-server/badge.svg)](/listings/mapbox--mcp-server)

HTML

<a href="/listings/mapbox--mcp-server"><img src="/api/listings/mapbox--mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Fork the repository and clone your fork 2. Install dependencies: `npm install` 3. Make your changes following our coding standards 4. Run tests and linting: `npm test && npm run lint` 5. Add tests for any new functionality 6. Submit a pull request with a clear description

All contributions must pass our CI checks and code review process. See [docs/engineering_standards.md](./docs/engineering_standards.md) for detailed requirements.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 763 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Mapbox MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@mapbox/mcp-server)](https://www.npmjs.com/package/@mapbox/mcp-server)
  3. Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs.
  4. ## Unlock Geospatial Intelligence for Your AI Applications
  5. 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:
  6. - **Global geocoding** to convert addresses and place names to coordinates and vice versa
  7. - **Points of interest (POI) search** across millions of businesses, landmarks, and places worldwide
  8. - **Multi-modal routing** for driving, walking, and cycling with real-time traffic
  9. - **Travel time matrices** to analyze accessibility and optimize logistics
  10. - **Route optimization** to find the optimal visiting order for multiple stops (traveling salesman problem)
  11. - **Map matching** to snap GPS traces to the road network for clean route visualization
  12. - **Isochrone generation** to visualize areas reachable within specific time or distance constraints
  13. - **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
  14. - **Static map images** to create visual representations of locations, routes, and geographic data
  15. - **Offline geospatial calculations** for distance, area, bearing, buffers, and spatial analysis without requiring API calls
  16. 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
  17. ![Mapbox MCP Server Demo](./assets/mapbox_mcp_server.gif)
  18. # Usage
  19. **A Mapbox access token is required to use this MCP server.**
  20. ## Hosted MCP Endpoint
  21. For quick access, you can use our hosted MCP endpoint:
  22. **Endpoint**: https://mcp.mapbox.com/mcp
  23. For detailed setup instructions for different clients and API usage, see the [Hosted MCP Server Guide](./docs/hosted-mcp-guide.md).
  24. To get a Mapbox access token:
  25. 1. Sign up for a free Mapbox account at [mapbox.com/signup](https://www.mapbox.com/signup/)
  26. 2. Navigate to your [Account page](https://account.mapbox.com/)
  27. 3. Create a new token or use the default public token
  28. For more information about Mapbox access tokens, see the [Mapbox documentation on access tokens](https://docs.mapbox.com/help/dive-deeper/access-tokens/).
  29. ## Integration Guides
  30. For detailed setup instructions for different integrations, refer to the following guides:
  31. - [Claude Desktop Setup](./docs/claude-desktop-setup.md) - Instructions for configuring Claude Desktop to work with this MCP server
  32. - [Goose Setup](./docs/goose-setup.md) - Setting up Goose AI agent framework
  33. - [VS Code Setup](./docs/vscode-setup.md) - Setting up a development environment in Visual Studio Code
  34. - [Cursor AI IDE Setup](./docs/cursor-setup.md) - Setting up a development environment in Cursor AI IDE
  35. - [Smolagents Integration](./docs/using-mcp-with-smolagents/README.md) - Example showing how to connect Smolagents AI agents to Mapbox's tools
  36. - **[Importing Tools Directly](./docs/importing-tools.md)** - Use Mapbox tools in your own applications without running the MCP server
  37. - **[`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
  38. - **[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
  39. ## Example Prompts
  40. Try these prompts with Claude Desktop or other MCP clients after setup:
  41. ### Location Grounding
  42. 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.
  43. Each of the four prompts below exercises a different strategy in one tool call:
  44. - **Neighborhood** — _"What neighborhood is 47.6097, -122.3408, and what's around me?"_
  45. - **POI** — _"Coffee shops within a 10-minute walk of 40.7580, -73.9855"_
  46. - **Region** — _"What can I reach in a 15-minute walk from 37.7749, -122.4194?"_
  47. - **Routing** — _"Closest routable point to drop someone off at 34.0522, -118.2437"_
  48. ### Location Discovery
  49. - "Find coffee shops within walking distance of the Empire State Building"
  50. - "I want to go from Seattle to Portland, is there a Starbucks along the way?"
  51. - "Show me gas stations along the route from Boston to New York"
  52. - "What restaurants are near Times Square?"
  53. ### Navigation & Travel
  54. - "Get driving directions from LAX to Hollywood with current traffic"
  55. - "How long would it take to walk from Central Park to Times Square?"
  56. - "How much climbing is on a bike ride from the Ferry Building to Twin Peaks?"
  57. - "Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi during rush hour"
  58. ### Visualization & Maps
  59. - "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
  60. - "Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf with markers at both locations"
  61. - "Show me a satellite view of Manhattan with key landmarks marked"
  62. - "Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"
  63. - "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
  64. ### Analysis & Planning
  65. - "Show me areas reachable within 30 minutes of downtown Portland by car"
  66. - "Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
  67. - "Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
  68. - "Optimize a delivery route for these 8 addresses: [list of addresses]"
  69. ### GPS & Route Matching
  70. - "Clean up this GPS trace and show the actual route on roads: [list of coordinates with timestamps]"
  71. - "Snap this recorded bicycle ride to the cycling network: [GPS coordinates]"
  72. - "Match this driving route to the road network and show traffic congestion levels"
  73. ### Offline Geospatial Calculations
  74. - "What's the distance in miles between these two coordinates?"
  75. - "Calculate the area of this polygon in square kilometers"
  76. - "Is the point at 37.7749°N, 122.4194°W inside this service area polygon?"
  77. - "What's the bearing from San Francisco to New York?"
  78. - "Find the midpoint between London and Paris"
  79. - "Create a 5-mile buffer zone around this location"
  80. - "Calculate the centroid of this neighborhood boundary"
  81. - "What's the bounding box for these route coordinates?"
  82. - "Simplify this complex polygon to reduce the number of points"
  83. ### Tips for Better Results
  84. - Be specific about locations (use full addresses or landmark names)
  85. - Specify your preferred travel method (driving, walking, cycling)
  86. - Include time constraints when relevant ("during rush hour", "at 3 PM")
  87. - Ask for specific output formats when needed ("as a map image", "in JSON format")
  88. > **Detailed examples:** See [examples/search-along-route.md](./examples/search-along-route.md) for comprehensive examples of the search-along-route prompt with different use cases and MCP Inspector testing instructions.
  89. ## Resources
  90. 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.
  91. ### Available Resources
  92. #### Mapbox Categories Resource
  93. **URI Pattern**: `mapbox://categories` or `mapbox://categories/{language}`
  94. 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").
  95. **Examples**:
  96. - `mapbox://categories` - Default (English) category list
  97. - `mapbox://categories/ja` - Japanese category names
  98. - `mapbox://categories/es` - Spanish category names
  99. **Accessing Resources**:
  100. - **Clients with native MCP resource support**: Use the `resources/read` MCP protocol method
  101. - **Clients without resource support**: Use the `resource_reader_tool` with the resource URI
  102. ## Rich Map Previews (`render_map_tool`)
  103. 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:
  104. - **Claude Desktop** ✅
  105. - **VS Code with GitHub Copilot** ✅
  106. - **Claude Code** ✅
  107. - **[Goose](https://github.com/block/goose)** ✅
  108. **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.
  109. 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.
  110. #### A map next to the chat in ChatGPT
  111. In ChatGPT, `render_map_tool` maps open as a tab next to the chat and stay open. You can also open an empty map from "+" → "More tools" → **Mapbox Map**. The map shares its view and the selected place (a pin, a search result, or a base map label such as a shop or a neighborhood) with the conversation, and in ChatGPT Desktop it registers WebMCP tools (`redraw_map`, `search_map`, `add_places`, `move_map`, `read_map`) so the model draws on the open map instead of opening another. On the web, a follow-up opens another map. Hosts without the [OpenAI MCP Extensions](https://developers.openai.com/plugins/build/extensions) ignore all of this.
  112. #### CLIENT_NEEDS_RESOURCE_FALLBACK
  113. **Resource Fallback Tools (Opt-In for Non-Compliant Clients)**
  114. 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.
  115. **Fallback Tools:**
  116. - `resource_reader_tool` - Generic fallback for reading any resource by URI
  117. - `category_list_tool` - Provides access to category list (mapbox://categories)
  118. **By default, these tools are NOT included** (assumes your client supports resources). If your client doesn't support resources, enable the fallback tools:
  119. ```bash
  120. export CLIENT_NEEDS_RESOURCE_FALLBACK=true
  121. ```
  122. **When to set this:**
  123. - ✅ Set to `true` if using smolagents or other clients without resource support
  124. - ❌ Leave unset (default) if using Claude Desktop, VS Code, MCP Inspector, or any resource-capable client
  125. - ❌ Leave unset if unsure (most clients support resources)
  126. ## Tools
  127. ### Utility Tools
  128. #### Resource Reader Tool
  129. 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.
  130. **Parameters**:
  131. - `uri`: The resource URI to read (e.g., `mapbox://categories`, `mapbox://categories/ja`)
  132. **Example Usage**:
  133. - Read default categories: `{"uri": "mapbox://categories"}`
  134. - Read Japanese categories: `{"uri": "mapbox://categories/ja"}`
  135. **Note**: If your MCP client supports native resources, prefer using the resource API directly for better performance.
  136. ### Offline Geospatial Tools
  137. These tools perform geospatial calculations completely offline without requiring Mapbox API calls. They use [Turf.js](https://turfjs.org/) for accurate geographic computations and work anywhere, even without internet connectivity.
  138. #### Distance Tool
  139. Calculate the distance between two geographic coordinates using the Haversine formula.
  140. **Features**:
  141. - Supports multiple units: kilometers, miles, meters, feet, nautical miles
  142. - Accurate great-circle distance calculation
  143. - No API calls required
  144. **Example Usage**: "What's the distance between San Francisco (37.7749°N, 122.4194°W) and New York (40.7128°N, 74.0060°W)?"
  145. #### Points Within Polygon Tool
  146. Test one or more points against a polygon or multipolygon, returning only those inside. Handles a single point or a batch in one call.
  147. **Features**:
  148. - Works with complex polygons including holes
  149. - Supports multipolygons
  150. - Batch-tests any number of points in one call
  151. - Useful for geofencing, delivery zone validation, and customer segmentation
  152. **Example Usage**: "Which of these delivery addresses are inside our service area?"
  153. #### Destination Tool
  154. Calculate a destination point given a starting point, bearing, and distance using geodesic (great-circle) offset.
  155. **Features**:
  156. - Straight-line offset, not a routed path
  157. - Useful for "find a point 5km north of X" or constructing search offsets
  158. - No API calls required
  159. **Example Usage**: "What's the point 10km northeast of the Space Needle?"
  160. #### Bearing Tool
  161. Calculate the compass direction (bearing) from one coordinate to another.
  162. **Features**:
  163. - Returns bearing in degrees (0-360°)
  164. - Provides cardinal direction (N, NE, E, SE, S, SW, W, NW)
  165. - Useful for navigation and directional queries
  166. **Example Usage**: "What direction should I head to go from here to the airport?"
  167. #### Midpoint Tool
  168. Find the geographic midpoint between two coordinates along the great circle path.
  169. **Features**:
  170. - Calculates true midpoint on Earth's curved surface
  171. - Useful for meeting point suggestions
  172. - Handles long-distance calculations correctly
  173. **Example Usage**: "What's halfway between San Francisco and New York?"
  174. #### Centroid Tool
  175. Calculate the geometric center (centroid) of a polygon or multipolygon.
  176. **Features**:
  177. - Works with complex shapes
  178. - Returns arithmetic mean of all points
  179. - Useful for placing labels or markers
  180. **Example Usage**: "Where should I place a marker for this neighborhood boundary?"
  181. #### Area Tool
  182. Calculate the area of a polygon.
  183. **Features**:
  184. - Supports multiple units: square meters, square kilometers, acres, hectares, square miles, square feet
  185. - Accurate area calculation on Earth's surface
  186. - Works with polygons of any size
  187. **Example Usage**: "What's the area of this park in acres?"
  188. #### Bounding Box Tool
  189. Calculate the minimum bounding box (bbox) that contains a geometry.
  190. **Features**:
  191. - Works with points, lines, polygons, and multipolygons
  192. - Returns [minLongitude, minLatitude, maxLongitude, maxLatitude]
  193. - Useful for viewport calculations and spatial indexing
  194. **Example Usage**: "What's the bounding box for this route?"
  195. #### Buffer Tool
  196. Create a buffer zone (polygon) around a point, line, or polygon.
  197. **Features**:
  198. - Supports multiple distance units
  199. - Creates circular buffers around points
  200. - Useful for proximity analysis and creating zones of influence
  201. **Example Usage**: "Show me a 5km buffer zone around this location"
  202. #### Simplify Tool
  203. Reduce the number of vertices in a line or polygon using the Douglas-Peucker algorithm.
  204. **Features**:
  205. - Configurable tolerance for detail level
  206. - Preserves overall shape while reducing complexity
  207. - Useful for reducing file sizes and improving rendering performance
  208. - Option to maintain topology (prevent self-intersections)
  209. **Example Usage**: "Simplify this complex boundary to reduce the number of points"
  210. #### Length Tool
  211. Measure the total length of a line defined by a series of coordinates.
  212. **Features**:
  213. - Supports kilometers, miles, meters, and feet
  214. - Useful for measuring a drawn route, path, or boundary without a routing API call
  215. **Example Usage**: "How long is this hiking trail?"
  216. #### Convex Tool
  217. Compute the convex hull of a set of points — the smallest convex polygon containing all of them.
  218. **Features**:
  219. - Useful for bounding-area analysis or estimating coverage area
  220. - Works offline without API calls
  221. **Example Usage**: "What's the smallest polygon that contains all of these store locations?"
  222. #### Nearest Point Tool
  223. Find the nearest point in a collection to a given target point.
  224. **Features**:
  225. - More efficient than calling `distance_tool` for each candidate and sorting
  226. - Useful for finding the closest store, stop, or landmark to a location
  227. **Example Usage**: "Which of these stores is closest to my current location?"
  228. #### Nearest Point on Line Tool
  229. Snap a point to the nearest position on a line or route, returning that point and the distance to it.
  230. **Features**:
  231. - Useful for "which point on this route is closest to my location?" or map-matching without an API call
  232. **Example Usage**: "Where on this hiking trail am I closest to right now?"
  233. #### Union, Intersect, and Difference Tools
  234. 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.
  235. **Features**:
  236. - Useful for combining service areas, finding coverage overlap, or computing exclusion zones (e.g. "what's covered by zone A but not zone B?")
  237. - Works entirely offline — no API calls required
  238. - Each returns a `render_map_tool` reference so the result can be visualized directly
  239. **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?"
  240. ### Mapbox API Tools
  241. #### Category List Tool (Deprecated)
  242. **⚠️ Deprecated**: Use the `resource_reader_tool` with URI `mapbox://categories` instead, or access the `mapbox://categories` resource directly if your client supports MCP resources.
  243. This tool is maintained for backward compatibility with clients that don't support MCP resources or the resource_reader_tool.
  244. #### Matrix Tool
  245. Calculates travel times and distances between multiple points using [Mapbox Matrix API](https://www.mapbox.com/matrix-api). Features include:
  246. - Efficient one-to-many, many-to-one or many-to-many routing calculations
  247. - Support for different travel profiles (driving-traffic, driving, walking, cycling)
  248. - Departure time specification for traffic-aware calculations
  249. - Route summarization with distance and duration metrics
  250. - Control approach (curb/unrestricted) and range of allowed departure bearings
  251. #### Static image tool
  252. Generates static map images using the [Mapbox static image API](https://docs.mapbox.com/api/maps/static-images/). Features include:
  253. - Custom map styles (streets, outdoors, satellite, etc.)
  254. - Adjustable image dimensions and zoom levels
  255. - Support for multiple markers with custom colors and labels
  256. - Overlay options including polylines and polygons
  257. - Auto-fitting to specified coordinates
  258. #### Category search tool
  259. Performs a category search using the [Mapbox Search Box category search API](https://docs.mapbox.com/api/search/search-box/#category-search). Features include:
  260. - Search for points of interest by category (restaurants, hotels, gas stations, etc.)
  261. - Filtering by geographic proximity
  262. - Customizable result limits
  263. - Rich metadata for each result
  264. - Support for multiple languages
  265. #### Reverse geocoding tool
  266. Performs reverse geocoding using the [Mapbox geocoding V6 API](https://docs.mapbox.com/api/search/geocoding/#reverse-geocoding). Features include:
  267. - Convert geographic coordinates to human-readable addresses
  268. - Customizable levels of detail (street, neighborhood, city, etc.)
  269. - Results filtering by type (address, poi, neighborhood, etc.)
  270. - Support for multiple languages
  271. - Rich location context information
  272. #### Ground location tool
  273. 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.
  274. **Features**:
  275. - Classifies the query (routing, neighborhood context, POI search, or region/reachability) and fetches only the relevant data
  276. - Nearby POI search by category, when requested
  277. - Travel-time reachability summary (isochrone-based)
  278. - Returns a `render_map_tool` reference with the grounded location and nearby POIs plotted
  279. **Example Usage**: "What neighborhood is this coordinate in, and are there any coffee shops nearby?"
  280. #### Place details tool
  281. 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.
  282. **Example Usage**: "Tell me more about that first coffee shop result — hours, phone number, and website"
  283. #### Directions tool
  284. Fetches routing directions using the [Mapbox Directions API](https://docs.mapbox.com/api/navigation/directions/). Features include:
  285. - Support for different routing profiles: driving (with live traffic or typical), walking, and cycling
  286. - Route from multiple waypoints (2-25 coordinate pairs)
  287. - Alternative routes option
  288. - Route annotations (distance, duration, speed, congestion)
  289. - Scheduling options:
  290. - Future departure time (`depart_at`) for driving and driving-traffic profiles
  291. - Desired arrival time (`arrive_by`) for driving profile only
  292. - Profile-specific optimizations:
  293. - Driving: vehicle dimension constraints (height, width, weight)
  294. - Exclusion options for routing:
  295. - Common exclusions: ferry routes, cash-only tolls
  296. - Driving-specific exclusions: tolls, motorways, unpaved roads, tunnels, country borders, state borders
  297. - Custom point exclusions (up to 50 geographic points to avoid)
  298. - GeoJSON geometry output format
  299. #### Isochrone tool
  300. Computes areas that are reachable within a specified amount of times from a location using [Mapbox Isochrone API](https://docs.mapbox.com/api/navigation/isochrone/). Features include:
  301. - Support for different travel profiles (driving, walking, cycling)
  302. - Customizable travel times or distances
  303. - Multiple contour generation (e.g., 15, 30, 45 minute ranges)
  304. - Optional departure or arrival time specification
  305. - Color customization for visualization
  306. #### Search and geocode tool
  307. Uses the [Mapbox Search Box Text Search API](https://docs.mapbox.com/api/search/search-box/#search-request) endpoint to power searching for and geocoding POIs, addresses, places, and any other types supported by that API.
  308. 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.
  309. #### Map matching tool
  310. Snaps GPS traces to the road network using the [Mapbox Map Matching API](https://docs.mapbox.com/api/navigation/map-matching/). Features include:
  311. - Convert noisy GPS traces to clean routes on the road network
  312. - Support for different travel profiles (driving, driving-traffic, walking, cycling)
  313. - Handle up to 100 coordinate pairs per request
  314. - Optional timestamps for improved accuracy based on speed
  315. - Configurable snap radiuses for different GPS quality levels
  316. - Route annotations (speed limits, distance, duration, traffic congestion)
  317. - Multiple geometry output formats (GeoJSON, polyline)
  318. **Example Usage**: "Clean up this GPS trace and snap it to roads: [coordinates with timestamps]"
  319. #### Optimization tool
  320. Finds the optimal route through multiple locations using the [Mapbox Optimization API](https://docs.mapbox.com/api/navigation/optimization/). Features include:
  321. - Solve traveling salesman problem (TSP) for 2-12 locations
  322. - Support for different travel profiles (driving, driving-traffic, walking, cycling)
  323. - Flexible start and end point configuration
  324. - Roundtrip or one-way trip optimization
  325. - Turn-by-turn navigation instructions (optional)
  326. - Route annotations (distance, duration, speed)
  327. - Multiple geometry output formats (GeoJSON, polyline)
  328. **Example Usage**: "Find the optimal route to visit these 5 stops: [list of addresses or coordinates]"
  329. **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.
  330. #### Elevation tool
  331. Gets ground elevation from Mapbox's terrain data ([Mapbox Terrain-DEM v1](https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-dem-v1/)). Give it up to 25 places for the height above sea level of each, or a line for:
  332. - Total climb and descent
  333. - The highest and lowest points, and how far along the line they are
  334. - An elevation profile of up to 50 points
  335. The line can be a `path` of coordinates, or the `route_ref` from a `directions_tool` or `map_matching_tool` result, which the tool turns back into the full route itself. The server reads the terrain tiles and decodes each pixel's height, so values aren't rounded to contour steps the way Tilequery's Terrain v2 contours are. Points along a line share tiles, and long lines are read at a coarser zoom so a call stays under 50 tile requests; `resolution_m` in the result says how coarse. Swings under 2 m don't count toward climb or descent, so DEM noise on flat ground doesn't add up. Heights are of the ground, not of buildings or bridges. The result includes a map ref with the line and its high and low points.
  336. **Example Usage**: "How hilly is the bike route from the Ferry Building to Twin Peaks?" or "How high is Longs Peak?"
  337. #### Feedback tool
  338. Sends a user's feedback about the app or agent to its developer, through the [Mapbox Feedback API](https://docs.mapbox.com/api/feedback/) (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](https://docs.mapbox.com/android/navigation/guides/feedback-agent/), it's for anything about your product that helps you understand what users need, for example:
  339. - A place that has closed, has wrong details, or sits on the wrong spot
  340. - A place or address that can't be found
  341. - A closed road, a wrong speed limit, or traffic shown wrong
  342. - A route with an illegal turn or entrance, or no route at all
  343. - Something about the app itself, such as a bug or a suggestion (`application_issue`)
  344. 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.
  345. 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.
  346. **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`.
  347. **Example Usage**: "Blue Bottle on Mint St closed last year, can you send that as feedback?"
  348. #### Report tool
  349. 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.
  350. 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.
  351. It uses the endpoint the Feedback API team added for the [Mapbox CLI](https://github.com/mapbox/mapbox-cli)'s `mapbox report` command. To leave the tool out, start the server with `--disable-tools report_tool`.
  352. **Example Usage**: "The map didn't draw any of my isochrones. Can you let the Mapbox MCP team know?"
  353. #### List public tokens tool
  354. 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.
  355. 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.
  356. It never returns secret or temporary tokens, and it can't create tokens (that needs `tokens:write`; the [DevKit server](https://github.com/mapbox/mcp-devkit-server)'s `create_token_tool` does it).
  357. **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`.
  358. **Example Usage**: "Build me a single-page site that shows our three store locations on a Mapbox map."
  359. # Development
  360. ## Inspecting server
  361. ### Using Node.js
  362. ```sh
  363. # Run the built image
  364. npm run inspect:build
  365. ```
  366. ### Using Docker
  367. ```sh
  368. # Build the Docker image
  369. docker build -t mapbox-mcp-server .
  370. # Run and inspect the server
  371. npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server
  372. ```
  373. ## Create new tool
  374. ```sh
  375. npx plop create-tool
  376. # provide tool name without suffix (e.g. Search)
  377. ```
  378. ## Releasing a New Version
  379. ```sh
  380. # 1. Bump version in package.json
  381. npm version <new-version> --no-git-tag-version
  382. # 2. Sync version to manifest.json and server.json
  383. npm run sync-manifest
  384. # 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
  385. npm run changelog:prepare-release <new-version>
  386. # 4. Update package-lock.json
  387. npm install
  388. # 5. Review changes, then commit and tag
  389. git add package.json package-lock.json manifest.json server.json CHANGELOG.md
  390. git commit -m "Release v<new-version>"
  391. git tag v<new-version>
  392. git push && git push --tags
  393. ```
  394. **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.
  395. ## OpenTelemetry Tracing
  396. This MCP server includes comprehensive OpenTelemetry tracing for production observability:
  397. ### Quick Demo
  398. ```sh
  399. # 1. Copy the example configuration
  400. cp .env.example .env
  401. # 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing
  402. # 3. Start Jaeger for local development
  403. npm run tracing:jaeger:start
  404. # 4. Run the server (it will automatically use .env configuration)
  405. npm run inspect:build
  406. # 5. View traces at http://localhost:16686
  407. # 6. Stop Jaeger when done
  408. npm run tracing:jaeger:stop
  409. ```
  410. **Note:** The server automatically loads configuration from your `.env` file at startup. The `.env.example` file includes configuration examples for multiple observability platforms.
  411. ### Supported Observability Platforms
  412. Configuration examples included in `.env.example` for:
  413. **Cloud Providers:**
  414. - ☁️ AWS X-Ray
  415. - ☁️ Azure Monitor (Application Insights)
  416. - ☁️ Google Cloud Trace
  417. **SaaS Platforms:**
  418. - 📊 Datadog
  419. - 📊 New Relic
  420. - 📊 Honeycomb
  421. - 📊 Any OTLP-compatible backend
  422. ### Production Configuration
  423. See [docs/tracing.md](./docs/tracing.md) for complete setup instructions including:
  424. - 🔧 Platform-specific configuration guides
  425. - 📊 Authentication and endpoint setup
  426. - 🎯 Custom trace attributes and context
  427. - 🚀 Performance optimization (minimal overhead)
  428. - 🔍 Troubleshooting and debugging
  429. **Tracing Features:**
  430. - ✅ Configuration loading tracing (.env file loading)
  431. - ✅ Automatic tool execution tracing
  432. - ✅ HTTP request instrumentation with CloudFront correlation IDs
  433. - ✅ Configurable exporters (console, OTLP)
  434. - ✅ Security-conscious (data protection, JWT validation)
  435. - ✅ Production-ready (<1% CPU overhead)
  436. ## Contributing
  437. We welcome contributions to the Mapbox MCP Server! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting a pull request.
  438. Full standards and guidelines:
  439. - **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Getting started, PR process, quick reference
  440. - **[Engineering Standards (docs/engineering_standards.md)](./docs/engineering_standards.md)** - Complete code quality, testing, documentation, and collaboration standards
  441. - **[Claude Code Guide (CLAUDE.md)](./CLAUDE.md)** - Standards and patterns for contributors using Claude Code
  442. - **[AI Agent Instructions (AGENTS.md)](./AGENTS.md)** - Guide for other AI coding assistants (Cursor, Continue, Aider, etc.)
  443. - **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Best practices for using GitHub Copilot responsibly
  444. ### Quick Start for Contributors
  445. 1. Fork the repository and clone your fork
  446. 2. Install dependencies: `npm install`
  447. 3. Make your changes following our coding standards
  448. 4. Run tests and linting: `npm test && npm run lint`
  449. 5. Add tests for any new functionality
  450. 6. Submit a pull request with a clear description
  451. All contributions must pass our CI checks and code review process. See [docs/engineering_standards.md](./docs/engineering_standards.md) for detailed requirements.
  452. ## Data Usage & Privacy
  453. ### What data is sent to Mapbox APIs
  454. When you use the MCP server tools, the following data is sent directly from your environment to Mapbox APIs:
  455. - **Geocoding tools**: Address/location text, coordinates, country/region filters
  456. - **Search tools**: Search queries, location coordinates for proximity, category filters
  457. - **Directions tool**: Start/end coordinates, waypoints, routing preferences, vehicle constraints
  458. - **Matrix tool**: Multiple coordinate pairs, travel profile, departure times
  459. - **Static map tool**: Coordinates, zoom level, styling preferences, marker information
  460. - **Isochrone tool**: Origin coordinates, time/distance parameters, travel profile
  461. ### Your privacy
  462. - **Local execution**: All API calls are made directly from your environment to Mapbox APIs
  463. - **Token security**: Your Mapbox API token remains on your local machine and is never transmitted to or stored by this MCP server
  464. - **No data storage**: This MCP server does not store, log, or collect any of your data or API requests
  465. - **Direct communication**: There is no intermediary server between you and Mapbox APIs
  466. ### Third-party data usage
  467. - **Mapbox's privacy policy** governs data sent to their APIs: https://www.mapbox.com/legal/privacy/
  468. - **API usage**: Standard Mapbox API terms apply to all requests made through these tools
  469. - **Data retention**: Refer to Mapbox's documentation for their data retention policies
  470. ## Support & Contact
  471. ### For MCP Server Issues
  472. - **Email**: mcp-feedback@mapbox.com
  473. - **GitHub Issues**: [Report bugs and feature requests](https://github.com/mapbox/mcp-server/issues)
  474. ### For Mapbox API Questions
  475. - **Mapbox Support**: https://support.mapbox.com/
  476. - **Documentation**: https://docs.mapbox.com/
  477. - **API Status**: https://status.mapbox.com/
  478. ### Maintenance Commitment
  479. This MCP server is officially maintained by Mapbox, Inc. We provide:
  480. - Regular updates for new Mapbox API features
  481. - Bug fixes and security updates
  482. - Compatibility with latest MCP protocol versions
  483. - Community support through GitHub issues
  484. ---
  485. [MIT License](LICENSE.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.