Mapbox MCP Server (mapbox/mcp-server)

Mapbox MCP Server

https://github.com/mapbox/mcp-server
Admin
A Node.js server implementing the Model Context Protocol for Mapbox APIs, enabling AI agents to...

Tokens:31,465
Snippets:453
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Mapbox MCP Server

The Mapbox MCP Server is a Node.js implementation of the Model Context Protocol (MCP) that provides AI agents and applications with comprehensive geospatial intelligence capabilities through Mapbox APIs. It transforms any AI system into a geospatially-aware application capable of understanding places, navigating the physical world, and accessing rich location data including global geocoding, points of interest search, multi-modal routing with real-time traffic, travel time matrices, route optimization, map matching, isochrone generation, and static map images.

The server supports multiple integration methods including Claude Desktop, VS Code with GitHub Copilot, Cursor AI IDE, and Goose AI agent framework. It can be used as a standalone MCP server via NPX or Docker, or its tools can be imported directly into custom applications as a library. The package exports pre-configured tool instances ready for immediate use, as well as tool classes for custom instantiation with configurable HTTP pipelines. All exports support both ESM and CommonJS via dual builds.

## Installation

```bash
npm install @mapbox/mcp-server
```

## Claude Desktop Configuration

Configure Claude Desktop to use the Mapbox MCP Server by modifying `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "MapboxServer": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}
```

## Directions Tool

Fetches routing directions from Mapbox API based on provided coordinates and routing profile. Supports multiple travel modes (driving with traffic, driving, walking, cycling), alternative routes, scheduled departures, vehicle dimension constraints, and various exclusion options. Returns turn-by-turn navigation with distance, duration, and congestion information.

```typescript
import { directions } from '@mapbox/mcp-server/tools';

// Get driving directions from San Francisco to Los Angeles with traffic
const result = await directions.execute({
  coordinates: [
    { longitude: -122.4194, latitude: 37.7749 },  // San Francisco
    { longitude: -118.2437, latitude: 34.0522 }   // Los Angeles
  ],
  routing_profile: 'mapbox/driving-traffic',
  geometries: 'geojson',          // 'none' for compact response, 'geojson' for route visualization
  alternatives: true,              // Request up to 2 alternative routes
  depart_at: '2024-12-15T08:00:00Z', // Schedule departure time (ISO 8601)
  max_height: 4.0,                 // Vehicle height in meters (driving profiles only)
  max_weight: 20,                  // Vehicle weight in metric tons (driving profiles only)
  exclude: 'toll,ferry'            // Exclude toll roads and ferries
});

// Response includes routes with distance (meters), duration (seconds), and geometry
console.log(`Distance: ${result.routes[0].distance / 1609.34} miles`);
console.log(`Duration: ${Math.floor(result.routes[0].duration / 60)} minutes`);
```

## Search and Geocode Tool

Searches for places and geocodes addresses using the Mapbox Search Box API. Combines POI search and forward geocoding into a single unified tool. Supports proximity biasing, bounding box filtering, country restrictions, and ETA calculations.

```typescript
import { searchAndGeocode } from '@mapbox/mcp-server/tools';

// Search for coffee shops near a location
const result = await searchAndGeocode.execute({
  q: 'coffee shop',
  proximity: {
    longitude: -122.4194,
    latitude: 37.7749
  },
  language: 'en',
  types: ['poi'],
  poi_category: ['cafe', 'coffee'],
  auto_complete: true,
  // Optional: Get ETA to results
  eta_type: 'navigation',
  navigation_profile: 'walking',
  origin: { longitude: -122.4194, latitude: 37.7749 }
});

// Geocode an address
const address = await searchAndGeocode.execute({
  q: '1600 Pennsylvania Avenue NW, Washington DC',
  types: ['address'],
  country: ['US'],
  limit: 1
});

console.log(address.features[0].geometry.coordinates); // [longitude, latitude]
```

## Category Search Tool

Searches for points of interest by category using the Mapbox Search Box category search API. Useful for finding nearby restaurants, hotels, gas stations, and other business types.

```typescript
import { categorySearch } from '@mapbox/mcp-server/tools';

// Find restaurants near Times Square
const result = await categorySearch.execute({
  category: 'restaurant',
  proximity: {
    longitude: -73.9855,
    latitude: 40.7580
  },
  limit: 10,
  country: ['US'],
  poi_category_exclusions: ['fast_food'],
  format: 'formatted_text'  // or 'json_string' for raw GeoJSON
});

// Find gas stations within a bounding box
const gasStations = await categorySearch.execute({
  category: 'gas_station',
  bbox: [-122.5, 37.7, -122.3, 37.9],  // [minLon, minLat, maxLon, maxLat]
  limit: 25
});
```

## Reverse Geocode Tool

Converts geographic coordinates to human-readable addresses using the Mapbox Geocoding V6 API. Returns detailed location context including street, neighborhood, city, region, and country.

```typescript
import { reverseGeocode } from '@mapbox/mcp-server/tools';

// Convert coordinates to address
const result = await reverseGeocode.execute({
  longitude: -122.4194,
  latitude: 37.7749,
  types: ['address', 'neighborhood', 'place'],
  language: 'en',
  limit: 1,
  worldview: 'us',
  format: 'formatted_text'
});

// Get multiple results for a location
const multipleResults = await reverseGeocode.execute({
  longitude: -73.9857,
  latitude: 40.7484,
  types: ['address'],  // Must specify exactly one type when limit > 1
  limit: 5
});
```

## Isochrone Tool

Computes areas reachable within a specified time or distance from a location using the Mapbox Isochrone API. Generates polygon or linestring geometries representing travel time contours.

```typescript
import { isochrone } from '@mapbox/mcp-server/tools';

// Show areas reachable within 15, 30, and 45 minutes by car
const result = await isochrone.execute({
  profile: 'mapbox/driving-traffic',
  coordinates: {
    longitude: -122.4194,
    latitude: 37.7749
  },
  contours_minutes: [15, 30, 45],
  contours_colors: ['ff0000', '00ff00', '0000ff'],  // Red, green, blue
  polygons: true,
  denoise: 0.5,        // Remove smaller contours (0-1)
  generalize: 2000,    // Simplify geometry (meters)
  exclude: ['toll', 'ferry'],
  depart_at: '2024-12-15T08:00:00-08:00'
});

// Distance-based isochrones (walking)
const walkingDistance = await isochrone.execute({
  profile: 'mapbox/walking',
  coordinates: { longitude: -73.9857, latitude: 40.7484 },
  contours_meters: [500, 1000, 2000],
  polygons: true,
  generalize: 100
});
```

## Matrix Tool

Calculates travel times and distances between multiple points using the Mapbox Matrix API. Efficient for one-to-many, many-to-one, or many-to-many routing calculations.

```typescript
import { matrix } from '@mapbox/mcp-server/tools';

// Calculate travel times between hotels and a convention center
const result = await matrix.execute({
  coordinates: [
    { longitude: -104.9903, latitude: 39.7392 },  // Denver Convention Center
    { longitude: -104.9847, latitude: 39.7436 },  // Hotel 1
    { longitude: -104.9956, latitude: 39.7502 },  // Hotel 2
    { longitude: -104.9821, latitude: 39.7389 }   // Hotel 3
  ],
  profile: 'mapbox/driving-traffic',
  annotations: 'duration,distance',
  sources: '0',          // Convention center as only source
  destinations: '1;2;3'  // Hotels as destinations
});

// Access the duration matrix (seconds)
console.log(result.durations);  // [[null, 180, 240, 120]] - times from source to each destination

// Access the distance matrix (meters)
console.log(result.distances);  // [[null, 1500, 2000, 1000]]
```

## Static Map Image Tool

Generates static map images using the Mapbox Static Images API. Supports custom styles, markers, polyline overlays, and GeoJSON features.

```typescript
import { staticMapImage } from '@mapbox/mcp-server/tools';

// Create a map with markers
const result = await staticMapImage.execute({
  center: { longitude: -122.4194, latitude: 37.7749 },
  zoom: 12,
  size: { width: 600, height: 400 },
  style: 'mapbox/streets-v12',  // or 'mapbox/satellite-v9', 'mapbox/dark-v11'
  highDensity: true,  // 2x resolution
  overlays: [
    {
      type: 'marker',
      longitude: -122.4194,
      latitude: 37.7749,
      size: 'large',
      label: 'a',
      color: 'ff0000'
    },
    {
      type: 'marker',
      longitude: -122.4089,
      latitude: 37.7855,
      label: 'cafe',  // Maki icon name
      color: '00ff00'
    }
  ]
});

// Create a map with a route path overlay
const routeMap = await staticMapImage.execute({
  center: { longitude: -122.4194, latitude: 37.7749 },
  zoom: 11,
  size: { width: 800, height: 600 },
  overlays: [
    {
      type: 'path',
      encodedPolyline: '_p~iF~ps|U_ulLnnqC_mqNvxq`@',  // Encoded polyline
      strokeWidth: 5,
      strokeColor: '0000ff',
      strokeOpacity: 0.8
    }
  ]
});
```

## Map Matching Tool

Snaps GPS traces to the road network using the Mapbox Map Matching API. Converts noisy GPS coordinates into clean routes that follow actual roads.

```typescript
import { mapMatching } from '@mapbox/mcp-server/tools';

// Match a GPS trace to the road network
const result = await mapMatching.execute({
  coordinates: [
    { longitude: -122.4194, latitude: 37.7749 },
    { longitude: -122.4184, latitude: 37.7759 },
    { longitude: -122.4174, latitude: 37.7769 },
    { longitude: -122.4164, latitude: 37.7779 }
  ],
  profile: 'driving',
  timestamps: [1702648800, 1702648810, 1702648820, 1702648830],  // Unix timestamps
  radiuses: [25, 25, 25, 25],  // Snap radius in meters per point
  annotations: ['speed', 'distance', 'duration', 'congestion'],
  overview: 'full',
  geometries: 'geojson'
});

// Access the matched route
console.log(result.matchings[0].geometry);  // GeoJSON LineString
console.log(result.matchings[0].confidence);  // Match confidence (0-1)
```

## Optimization Tool

Finds the optimal route through multiple locations using the Mapbox Optimization API. Solves the traveling salesman problem for 2-12 waypoints.

```typescript
import { optimization } from '@mapbox/mcp-server/tools';

// Find optimal visiting order for multiple stops
const result = await optimization.execute({
  coordinates: [
    { longitude: -122.4194, latitude: 37.7749 },  // Start/End
    { longitude: -122.4089, latitude: 37.7855 },  // Stop 1
    { longitude: -122.3964, latitude: 37.7946 },  // Stop 2
    { longitude: -122.4474, latitude: 37.8044 },  // Stop 3
    { longitude: -122.4824, latitude: 37.7564 }   // Stop 4
  ],
  profile: 'mapbox/driving-traffic',
  source: 'first',       // Start at first coordinate
  destination: 'last',   // End at last coordinate (or 'any')
  roundtrip: false,      // One-way trip
  geometries: 'geojson',
  steps: true,           // Include turn-by-turn instructions
  annotations: ['duration', 'distance']
});

// Access optimized waypoint order
console.log(result.waypoints.map(w => w.waypoint_index));  // Optimal visiting order
console.log(result.trips[0].duration);  // Total trip duration in seconds
```

## Distance Tool (Offline)

Calculates the distance between two geographic coordinates using the Haversine formula. Works completely offline without API calls.

```typescript
import { distance } from '@mapbox/mcp-server/tools';

// Calculate distance between two points
const result = await distance.execute({
  from: { longitude: -122.4194, latitude: 37.7749 },  // San Francisco
  to: { longitude: -73.9857, latitude: 40.7484 },     // New York
  units: 'miles'  // 'kilometers', 'meters', 'feet', 'nauticalmiles'
});

console.log(`Distance: ${result.distance} miles`);  // ~2,565 miles
```

## Area Tool (Offline)

Calculates the area of a polygon. Works completely offline using Turf.js.

```typescript
import { area } from '@mapbox/mcp-server/tools';

// Calculate area of a polygon
const result = await area.execute({
  geometry: [
    [  // Outer ring
      [-122.4194, 37.7749],
      [-122.4089, 37.7749],
      [-122.4089, 37.7849],
      [-122.4194, 37.7849],
      [-122.4194, 37.7749]
    ]
  ],
  units: 'acres'  // 'meters', 'kilometers', 'feet', 'miles', 'hectares'
});

console.log(`Area: ${result.area} acres`);
```

## Buffer Tool (Offline)

Creates a buffer zone (polygon) around a point, line, or polygon. Works completely offline.

```typescript
import { buffer } from '@mapbox/mcp-server/tools';

// Create a 5km buffer around a point
const result = await buffer.execute({
  geometry: [-122.4194, 37.7749],  // Point as [longitude, latitude]
  distance: 5,
  units: 'kilometers'  // 'miles', 'meters', 'feet'
});

// Buffer around a line
const lineBuffer = await buffer.execute({
  geometry: [
    [-122.4194, 37.7749],
    [-122.4089, 37.7855],
    [-122.3964, 37.7946]
  ],
  distance: 100,
  units: 'meters'
});

console.log(result.geometry);  // GeoJSON Polygon
```

## Bearing Tool (Offline)

Calculates the compass direction (bearing) from one coordinate to another. Returns bearing in degrees and cardinal direction.

```typescript
import { bearing } from '@mapbox/mcp-server/tools';

const result = await bearing.execute({
  from: { longitude: -122.4194, latitude: 37.7749 },
  to: { longitude: -73.9857, latitude: 40.7484 }
});

console.log(`Bearing: ${result.bearing} degrees`);  // ~66 degrees
console.log(`Direction: ${result.direction}`);       // 'ENE'
```

## Midpoint Tool (Offline)

Finds the geographic midpoint between two coordinates along the great circle path.

```typescript
import { midpoint } from '@mapbox/mcp-server/tools';

const result = await midpoint.execute({
  from: { longitude: -122.4194, latitude: 37.7749 },  // San Francisco
  to: { longitude: -73.9857, latitude: 40.7484 }      // New York
});

console.log(result.midpoint);  // { longitude: -97.xxx, latitude: 41.xxx }
```

## Centroid Tool (Offline)

Calculates the geometric center (centroid) of a polygon or multipolygon.

```typescript
import { centroid } from '@mapbox/mcp-server/tools';

const result = await centroid.execute({
  geometry: [
    [
      [-122.42, 37.77],
      [-122.40, 37.77],
      [-122.40, 37.79],
      [-122.42, 37.79],
      [-122.42, 37.77]
    ]
  ]
});

console.log(result.centroid);  // { longitude: -122.41, latitude: 37.78 }
```

## Bounding Box Tool (Offline)

Calculates the minimum bounding box that contains a geometry.

```typescript
import { boundingBox } from '@mapbox/mcp-server/tools';

const result = await boundingBox.execute({
  geometry: [
    [-122.4194, 37.7749],
    [-122.4089, 37.7855],
    [-122.3964, 37.7946]
  ]
});

console.log(result.bbox);  // [minLon, minLat, maxLon, maxLat]
```

## Simplify Tool (Offline)

Reduces the number of vertices in a line or polygon using the Douglas-Peucker algorithm.

```typescript
import { simplify } from '@mapbox/mcp-server/tools';

const result = await simplify.execute({
  geometry: [
    [-122.4194, 37.7749],
    [-122.4184, 37.7759],
    [-122.4174, 37.7769],
    // ... many more points
  ],
  tolerance: 0.001,      // Simplification tolerance
  highQuality: true      // Maintain topology
});

console.log(result.geometry);  // Simplified LineString
```

## Building a Custom MCP Server

Import and use Mapbox tools in your own MCP server implementation with selective tool registration.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  directions,
  searchAndGeocode,
  isochrone,
  distance,
  area
} from '@mapbox/mcp-server/tools';

async function createCustomServer() {
  const server = new McpServer(
    { name: 'my-geo-server', version: '1.0.0' },
    { capabilities: { tools: {} } }
  );

  // Install only the tools you need
  directions.installTo(server);
  searchAndGeocode.installTo(server);
  isochrone.installTo(server);
  distance.installTo(server);  // Offline tool - no API calls
  area.installTo(server);      // Offline tool - no API calls

  const transport = new StdioServerTransport();
  await server.connect(transport);

  return server;
}

createCustomServer().catch(console.error);
```

## Custom HTTP Pipeline Configuration

Create tools with custom retry logic, user agents, and middleware policies.

```typescript
import { DirectionsTool, SearchAndGeocodeTool } from '@mapbox/mcp-server/tools';
import {
  HttpPipeline,
  UserAgentPolicy,
  RetryPolicy,
  TracingPolicy
} from '@mapbox/mcp-server/utils';

// Create custom pipeline
const pipeline = new HttpPipeline();
pipeline.usePolicy(new UserAgentPolicy('MyApp/2.0.0'));
pipeline.usePolicy(new RetryPolicy(5, 300, 5000));  // 5 retries, 300ms base, 5s max
pipeline.usePolicy(new TracingPolicy());

// Add custom logging policy
pipeline.usePolicy({
  id: 'request-logger',
  async handle(input, init, next) {
    console.log('Request:', input);
    const start = Date.now();
    const response = await next(input, init);
    console.log(`Response: ${response.status} (${Date.now() - start}ms)`);
    return response;
  }
});

// Create tools with custom pipeline
const httpRequest = pipeline.execute.bind(pipeline);
const customDirections = new DirectionsTool({ httpRequest });
const customSearch = new SearchAndGeocodeTool({ httpRequest });
```

## Summary

The Mapbox MCP Server provides a comprehensive suite of geospatial tools for AI applications, ranging from online API-based services for geocoding, routing, and map generation to offline computational geometry tools powered by Turf.js. The primary use cases include building AI travel assistants that can find routes and points of interest, logistics optimization applications that calculate travel time matrices and optimal delivery routes, location-based recommendation systems, and any application requiring spatial awareness such as geofencing, proximity analysis, or map visualization.

Integration patterns support multiple approaches: running as a standalone MCP server for Claude Desktop or other MCP clients, importing pre-configured tool instances for quick integration, or creating custom tool instances with configurable HTTP pipelines for advanced scenarios. The modular architecture allows developers to import only the tools they need, minimizing bundle size for client applications. Offline geometry tools work without API calls or internet connectivity, making them suitable for edge computing scenarios. All tools follow consistent patterns with Zod schema validation, structured responses, and comprehensive error handling.