Mapbox MCP Server

MCP Server for the Mapbox API.

Features

Navigation Tools

1. `mapbox_directions`

2. `mapbox_directions_by_places`

3. `mapbox_matrix`

4. `mapbox_matrix_by_places`

Search Tools

1. `mapbox_geocoding`

Claude Desktop Integration

Add this configuration to your Claude Desktop config file (typically located at `~/Library/Application Support/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "mapbox-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mapbox-mcp-server/build/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your-api-key"
      }
    }
  }
}

Setup

Prerequisites

• Node.js 16 or higher
• TypeScript 4.5 or higher
• A valid Mapbox API key

API Key

Get a Mapbox API key by following the instructions here.

Set your API key as an environment variable:

export MAPBOX_ACCESS_TOKEN=your_api_key_here

Rate Limits

• Directions API: 300 requests per minute
• Matrix API:
  • 60 requests per minute for driving/walking/cycling
  • 30 requests per minute for driving-traffic
• Geocoding API: 600 requests per minute

Deployment

Structure

In mapbox-mcp-server, we use the following structure to manage the server's handlers:

• `src/server/handlers/base.ts`: Base class for all handlers
• `src/server/registry.ts`: Registry for all handlers
• `src/server/main.ts`: Main entry point for the server

Each feature module follows this structure:

src/
├── types/          # Type definitions
├── schemas/        # Zod schemas for validation
├── tools/
│   ├── definitions/  # Tool definitions
│   └── handlers/     # Tool implementations
└── server/
    └── handlers/     # Handler classes

Class Diagram:

Process Diagram:

Error Handling

All tools implement comprehensive error handling:

• Input validation errors
• API request failures
• Rate limit errors
• Service-specific errors (e.g., no routes found, invalid coordinates)

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.