📌Overview

Purpose: The Mapbox MCP Server provides a set of tools and APIs to facilitate navigation and search functionalities using the Mapbox API.

Overview: The Mapbox MCP Server is designed to enhance location-based services by providing navigation tools for route planning and distance calculations, as well as search functionalities that enable users to find places and convert addresses to coordinates.

Key Features:

• Navigation Tools:
  • Includes capabilities like mapbox_directions and mapbox_matrix which allow users to compute routes and travel matrices between coordinates and places, supporting various travel profiles (e.g., driving, walking).
• Search Tools:
  • Provides mapbox_geocoding to facilitate the searching of places and conversion of addresses into geographic coordinates, enhancing location retrieval with filters and options for fuzzy matching.

---

Mapbox MCP Server

MCP Server for the Mapbox API.

Features

Navigation Tools

1. mapbox_directions

   • Get directions between coordinates.
   • Inputs:
     • coordinates ({latitude: number, longitude: number}[])
     • profile (optional): "driving-traffic", "driving", "walking", "cycling".
   • Returns: Route details with steps, distance, and duration.

2. mapbox_directions_by_places

   • Get directions between places using their names.
   • Inputs:
     • places (string[]): Array of place names.
     • profile (optional): "driving-traffic", "driving", "walking", "cycling".
     • language (optional): Two-letter language code.
   • Returns: Geocoding results, route details, and any errors.

3. mapbox_matrix

   • Calculate travel time and distance matrices between coordinates.
   • Inputs:
     • coordinates ({latitude: number, longitude: number}[])
     • profile (optional): "driving", "walking", "cycling".
     • annotations (optional): "duration", "distance", "duration,distance".
   • Returns: Matrix of durations and/or distances between points.

4. mapbox_matrix_by_places

   • Calculate travel time and distance matrices between places using their names.
   • Inputs:
     • places (string[]): Array of place names (2-25 places).
     • profile (optional): "driving", "walking", "cycling".
     • language (optional): Two-letter language code.
   • Returns: Geocoding results, matrix of durations and/or distances, and any errors.

Search Tools

1. mapbox_geocoding
   • Search for places and convert addresses into coordinates.
   • Inputs:
     • searchText (string): The place or address to search for.
     • limit (optional): Maximum number of results (1-10).
     • types (optional): Filter by place types.
   • Returns: Detailed location information including coordinates.

Claude Desktop Integration

To integrate with Claude Desktop, add the following configuration to your 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

The following structure is used to manage the server's handlers:

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

Error Handling

All tools implement comprehensive error handling, including validation errors, API request failures, rate limit errors, and service-specific errors.

License

This MCP server is licensed under the MIT License, allowing free use, modification, and distribution, subject to the terms of the license.