mapbox

The Mapbox MCP Server exposes a set of tools to interact with the Mapbox API through a consistent MCP interface. Key tools include mapbox_directions for routing between coordinates, mapbox_directions_by_places for routes between named places, mapbox_matrix and mapbox_matrix_by_places for travel-time and distance matrices, and mapbox_geocoding for forward geocoding from addresses or place names. Each tool validates inputs and returns structured results with route steps, distances, durations, and, where applicable, geocoding data and error information. To use the server, ensure the MAPBOX_ACCESS_TOKEN environment variable is set with a valid Mapbox API key, then invoke the desired tool with the appropriate inputs via your MCP client.

Common workflows include obtaining driving directions between coordinates, estimating travel times for multiple origins and destinations with matrices, and geocoding multiple place names to coordinates for batch processing. The server handles input validation, rate-limiting considerations, and error reporting to help you integrate Mapbox capabilities into your applications with predictable behavior.

Prerequisites:

• Node.js 16 or higher
• TypeScript 4.5 or higher (if building from source)
• A Mapbox API key

Installation steps:

1. Clone the repository or download the release package.

2. Install dependencies:

npm install

3. Build the server (if a build step exists in the project):

npm run build

4. Set up environment variables (example):

export MAPBOX_ACCESS_TOKEN=your_api_key_here

5. Run the MCP server (adjust paths as needed):

node build/index.js

6. Verify installation by sending a test request to one of the available tools (e.g., mapbox_geocoding) and confirming a valid response.

Environment variables: MAPBOX_ACCESS_TOKEN is required for authenticating with Mapbox services. Ensure your token has appropriate scopes for the APIs you plan to call. Rate limits follow Mapbox guidelines; plan retries and backoff accordingly. If you encounter errors, check that the token is valid, inputs conform to the described schemas (coordinate structures, place name arrays, etc.), and that you’re not exceeding per-minute limits for the used API (Directions, Matrix, Geocoding). The server architecture includes clear separation of handlers and a registry, making it easier to extend with additional tools if needed.