GitHub - mapbox/mcp-server: Mapbox Model Context Protocol (MCP) server (original) (raw)

Mapbox MCP Server

npm version

Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs.

Unlock Geospatial Intelligence for Your AI Applications

The Mapbox MCP Server transforms any AI agent or application into a geospatially-aware system by providing seamless access to Mapbox's comprehensive location intelligence platform. With this server, your AI can understand and reason about places, navigate the physical world, and access rich geospatial data including:

Whether you're building an AI travel assistant, logistics optimizer, location-based recommender, or any application that needs to understand "where", the Mapbox MCP Server provides the spatial intelligence to make it possible. You can also enable it on popular clients like Claude Desktop and VS Code. See below for details

Mapbox MCP Server Demo

Usage

A Mapbox access token is required to use this MCP server.

Hosted MCP Endpoint

For quick access, you can use our hosted MCP endpoint:

Endpoint: https://mcp.mapbox.com/mcp

For detailed setup instructions for different clients and API usage, see the Hosted MCP Server Guide.

To get a Mapbox access token:

  1. Sign up for a free Mapbox account at mapbox.com/signup
  2. Navigate to your Account page
  3. Create a new token or use the default public token

For more information about Mapbox access tokens, see the Mapbox documentation on access tokens.

Integration Guides

For detailed setup instructions for different integrations, refer to the following guides:

Example Prompts

Try these prompts with Claude Desktop or other MCP clients after setup:

Location Discovery

Navigation & Travel

Visualization & Maps

Analysis & Planning

Tips for Better Results

Resources

The MCP server exposes static reference data as MCP resources. Resources provide read-only access to data that clients can reference directly without making tool calls.

Available Resources

Mapbox Categories Resource

URI Pattern: mapbox://categories or mapbox://categories/{language}

Access the complete list of available category IDs for use with the category search tool. Categories can be used to filter search results by type (e.g., "restaurant", "hotel", "gas_station").

Examples:

Accessing Resources:

MCP-UI Support

This MCP server supports MCP-UI, an open specification that allows compatible clients to render interactive UI elements like embedded iframes. This provides a richer visual experience while maintaining full backwards compatibility with clients that don't support MCP-UI.

What is MCP-UI?

MCP-UI enables tools to return interactive UI resources alongside their standard output. Compatible clients can render these as embedded iframes, while clients without MCP-UI support simply ignore them and use the standard output.

Supported Tools

Benefits

Configuration

MCP-UI is enabled by default. To disable it:

Via Environment Variable:

ENABLE_MCP_UI=false npm run build

Via Command-Line Flag:

node dist/esm/index.js --disable-mcp-ui

In Claude Desktop config:

{ "mcpServers": { "mapbox": { "command": "npx", "args": ["-y", "@mapbox/mcp-server", "--disable-mcp-ui"], "env": { "MAPBOX_ACCESS_TOKEN": "your_token_here" } } } }

For more detailed information, including compatible clients, technical implementation details, and troubleshooting, see the MCP-UI documentation.

Tools

Utility Tools

Resource Reader Tool

Provides access to MCP resources for clients that don't support the native MCP resource API. Use this tool to read resources like the category list.

Parameters:

Example Usage:

Note: If your MCP client supports native resources, prefer using the resource API directly for better performance.

Mapbox API Tools

Category List Tool (Deprecated)

⚠️ Deprecated: Use the resource_reader_tool with URI mapbox://categories instead, or access the mapbox://categories resource directly if your client supports MCP resources.

This tool is maintained for backward compatibility with clients that don't support MCP resources or the resource_reader_tool.

Matrix Tool

Calculates travel times and distances between multiple points using Mapbox Matrix API. Features include:

Static image tool

Generates static map images using the Mapbox static image API. Features include:

Category search tool

Performs a category search using the Mapbox Search Box category search API. Features include:

Reverse geocoding tool

Performs reverse geocoding using the Mapbox geocoding V6 API. Features include:

Directions tool

Fetches routing directions using the Mapbox Directions API. Features include:

Isochrone tool

Computes areas that are reachable within a specified amount of times from a location using Mapbox Isochrone API. Features include:

Search and geocode tool

Uses the Mapbox Search Box Text Search API endpoint to power searching for and geocoding POIs, addresses, places, and any other types supported by that API. This tool consolidates the functionality that was previously provided by the ForwardGeocodeTool and PoiSearchTool (from earlier versions of this MCP server) into a single tool.

Development

Inspecting server

Using Node.js

Run the built image

npm run inspect:build

Using Docker

Build the Docker image

docker build -t mapbox-mcp-server .

Run and inspect the server

npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

Create new tool

npx plop create-tool

provide tool name without suffix (e.g. Search)

OpenTelemetry Tracing

This MCP server includes comprehensive OpenTelemetry tracing for production observability:

Quick Demo

1. Copy the example configuration

cp .env.example .env

2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

3. Start Jaeger for local development

npm run tracing:jaeger:start

4. Run the server (it will automatically use .env configuration)

npm run inspect:build

5. View traces at http://localhost:16686

6. Stop Jaeger when done

npm run tracing:jaeger:stop

Note: The server automatically loads configuration from your .env file at startup. The .env.example file includes configuration examples for multiple observability platforms.

Supported Observability Platforms

Configuration examples included in .env.example for:

Cloud Providers:

SaaS Platforms:

Production Configuration

See docs/tracing.md for complete setup instructions including:

Tracing Features:

Contributing

We welcome contributions to the Mapbox MCP Server! Please review our standards and guidelines before contributing:

Quick Start for Contributors

  1. Fork the repository and clone your fork
  2. Install dependencies: npm install
  3. Make your changes following our coding standards
  4. Run tests and linting: npm test && npm run lint
  5. Add tests for any new functionality
  6. Submit a pull request with a clear description

All contributions must pass our CI checks and code review process. See docs/engineering_standards.md for detailed requirements.

Data Usage & Privacy

What data is sent to Mapbox APIs

When you use the MCP server tools, the following data is sent directly from your environment to Mapbox APIs:

Your privacy

Third-party data usage

Support & Contact

For MCP Server Issues

For Mapbox API Questions

Maintenance Commitment

This MCP server is officially maintained by Mapbox, Inc. We provide:

MIT License