MCP Directory

How to add Mapbox MCP Server to Windsurf

Geospatial intelligence for AI: geocoding, POI search, routing, isochrones, matrices, and static maps via Mapbox APIs. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 347★ · stdio · apikey

Windsurf config for Mapbox MCP Server

npx -y @mapbox/mcp-server
{
  "mcpServers": {
    "mapbox-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@mapbox/mcp-server"
      ],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Mapbox MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Mapbox MCP Server's tools become available to Cascade.

Before you start

  • A Mapbox access token (free Mapbox account at mapbox.com/signup)
  • Node.js (for the npm package via npx) or Docker, for local stdio usage
  • An MCP-compatible client (Claude Desktop, Claude Code, VS Code, Cursor, etc.)

What Mapbox MCP Server can do in Windsurf

search_and_geocode_tool

Search for and geocode POIs, addresses, and places using the Mapbox Search Box Text Search API (consolidates the former forward-geocode and POI-search tools).

category_search_tool

Find all places matching a category (restaurants, hotels, gas stations, etc.) with proximity filtering, result limits, and multi-language support via the Search Box category search API.

reverse_geocode_tool

Convert geographic coordinates to human-readable addresses using the Geocoding V6 API, with configurable detail levels and type filtering.

directions_tool

Fetch routing directions for driving (with live or typical traffic), walking, and cycling across 2-25 waypoints, with alternatives, annotations, depart_at/arrive_by scheduling, vehicle constraints, and exclusions.

matrix_tool

Calculate travel-time and distance matrices between multiple points (one-to-many, many-to-one, many-to-many) with traffic-aware profiles via the Matrix API.

isochrone_tool

Compute areas reachable within given time or distance constraints from a location, generating multiple contours per request, via the Isochrone API.

optimization_tool

Solve the traveling-salesman problem to find the optimal visiting order for 2-12 locations, with roundtrip/one-way options and turn-by-turn output, via the Optimization API.

map_matching_tool

Snap noisy GPS traces (up to 100 coordinates) to the road network with optional timestamps, snap radiuses, and congestion annotations, via the Map Matching API.

Security

Requires a Mapbox access token (MAPBOX_ACCESS_TOKEN). For local stdio usage the token stays on your machine and API calls go directly from your environment to Mapbox APIs; the local server does not store or log data. The hosted endpoint (https://mcp.mapbox.com/mcp) supports OAuth or sending the token as an 'authorization: Bearer <token>' header. Data sent to Mapbox APIs is governed by Mapbox's privacy policy.

Mapbox MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Mapbox MCP Server config there under the "mcpServers" key and restart the client.

Is Mapbox MCP Server safe to use with Windsurf?

Requires a Mapbox access token (MAPBOX_ACCESS_TOKEN). For local stdio usage the token stays on your machine and API calls go directly from your environment to Mapbox APIs; the local server does not store or log data. The hosted endpoint (https://mcp.mapbox.com/mcp) supports OAuth or sending the token as an 'authorization: Bearer <token>' header. Data sent to Mapbox APIs is governed by Mapbox's privacy policy.

How do I authenticate?

You need a Mapbox access token. For local stdio usage set it in MAPBOX_ACCESS_TOKEN. For the hosted endpoint (https://mcp.mapbox.com/mcp) you can use the interactive OAuth flow or send the token as an 'authorization: Bearer <token>' header.

Can I use it without running a server locally?

Yes. Mapbox hosts the server at https://mcp.mapbox.com/mcp over Streamable HTTP. Add it in Claude Code with 'claude mcp add --transport http ... https://mcp.mapbox.com/mcp', or configure VS Code/Cursor/Claude Desktop/OpenAI to point at that URL.

Which tools work offline?

The geospatial calculation tools (distance, bearing, midpoint, centroid, area, bounding box, buffer, simplify, point-in-polygon) use Turf.js and run entirely offline; the geocoding, search, directions, matrix, isochrone, optimization, map-matching, and static-image tools call Mapbox APIs.

View repo Full Mapbox MCP Server page