MCP Server

🚀 Mapbox MCP Server

The Mapbox MCP Server is a Node.js server implementing the Model Context Protocol (MCP) for Mapbox APIs. It transforms any AI agent or application into a geospatially - aware system, offering seamless access to Mapbox's comprehensive location intelligence platform.

🚀 Quick Start

A Mapbox access token is required to use this MCP server. You can get a token by signing up for a free Mapbox account at mapbox.com/signup, navigating to your Account page, and creating a new token or using the default public token.

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.

✨ Features

• Global Geospatial Data Access: Enables AI to access rich geospatial data such as global geocoding, POI search, multi - modal routing, travel time matrices, isochrone generation, and static map images.
• Client Compatibility: Can be enabled on popular clients like Claude Desktop and VS Code.
• MCP - UI Support: Supports the MCP - UI open specification, providing a richer visual experience while maintaining full backwards compatibility.
• Comprehensive Tools: Offers a variety of utility and Mapbox API tools for different geospatial tasks.
• OpenTelemetry Tracing: Includes comprehensive tracing for production observability, supporting multiple observability platforms.

📦 Installation

• 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

💻 Usage Examples

Example Prompts

After setup, try these prompts with Claude Desktop or other MCP clients:

Location Discovery

• "Find coffee shops within walking distance of the Empire State Building"
• "Show me gas stations along the route from Boston to New York"
• "What restaurants are near Times Square?"

Navigation & Travel

• "Get driving directions from LAX to Hollywood with current traffic"
• "How long would it take to walk from Central Park to Times Square?"
• "Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi during rush hour"

Visualization & Maps

• "Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf with markers at both locations"
• "Show me a satellite view of Manhattan with key landmarks marked"
• "Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"

Analysis & Planning

• "Show me areas reachable within 30 minutes of downtown Portland by car"
• "Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
• "Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"

Tips for Better Results

• Be specific about locations (use full addresses or landmark names)
• Specify your preferred travel method (driving, walking, cycling)
• Include time constraints when relevant ("during rush hour", "at 3 PM")
• Ask for specific output formats when needed ("as a map image", "in JSON format")

📚 Documentation

Integration Guides

• Claude Desktop Setup - Instructions for configuring Claude Desktop to work with this MCP server
• Goose Setup - Setting up Goose AI agent framework with MCP - UI support
• VS Code Setup - Setting up a development environment in Visual Studio Code
• Cursor AI IDE Setup - Setting up a development environment in Cursor AI IDE
• Smolagents Integration - Example showing how to connect Smolagents AI agents to Mapbox's tools

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.

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:

• mapbox://categories - Default (English) category list
• mapbox://categories/ja - Japanese category names
• mapbox://categories/es - Spanish category names Accessing Resources:
• Clients with native MCP resource support: Use the resources/read MCP protocol method
• Clients without resource support: Use the resource_reader_tool with the resource URI

MCP - UI Support

This MCP server supports MCP - UI, an open specification that allows compatible clients to render interactive UI elements like embedded iframes.

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

• Static Map Image Tool: Returns both image data and an embeddable iframe URL for inline map visualization

Benefits

• Enhanced Experience: Compatible clients (e.g., Goose) can display maps inline without leaving the chat
• Backwards Compatible: Non - supporting clients (e.g., Claude Desktop) continue working unchanged
• No Configuration Required: MCP - UI is enabled by default

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:

• uri: The resource URI to read (e.g., mapbox://categories, mapbox://categories/ja) Example Usage:
• Read default categories: {"uri": "mapbox://categories"}
• Read Japanese categories: {"uri": "mapbox://categories/ja"} 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 efficient one - to - many, many - to - one or many - to - many routing calculations, support for different travel profiles, departure time specification, route summarization, and control of approach and departure bearings.

Static image tool

Generates static map images using the Mapbox static image API. Features include custom map styles, adjustable image dimensions and zoom levels, support for multiple markers, overlay options, and auto - fitting to specified coordinates.

Category search tool

Performs a category search using the Mapbox Search Box category search API. Features include searching for POIs by category, filtering by geographic proximity, customizable result limits, rich metadata, and support for multiple languages.

Reverse geocoding tool

Performs reverse geocoding using the Mapbox geocoding V6 API. Features include converting coordinates to addresses, customizable levels of detail, result filtering, support for multiple languages, and rich location context information.

Directions tool

Fetches routing directions using the Mapbox Directions API. Features include support for different routing profiles, multi - waypoint routing, alternative routes, route annotations, scheduling options, profile - specific optimizations, exclusion options, and GeoJSON geometry output format.

Isochrone tool

Computes areas that are reachable within a specified amount of times from a location using Mapbox Isochrone API. Features include support for different travel profiles, customizable travel times or distances, multiple contour generation, optional departure or arrival time specification, and color customization for visualization.

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.

🔧 Technical Details

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:

• ☁️ AWS X - Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace
• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Any OTLP - compatible backend

Production Configuration

See docs/tracing.md for complete setup instructions including platform - specific configuration guides, authentication and endpoint setup, custom trace attributes and context, performance optimization, and troubleshooting. Tracing Features:

• ✅ Configuration loading tracing (.env file loading)
• ✅ Automatic tool execution tracing
• ✅ HTTP request instrumentation with CloudFront correlation IDs
• ✅ Configurable exporters (console, OTLP)
• ✅ Security - conscious (data protection, JWT validation)
• ✅ Production - ready (<1% CPU overhead)

🤝 Contributing

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

• Engineering Standards (docs/engineering_standards.md) - Complete code quality, testing, documentation, and collaboration standards for all contributors
• Claude Code Guide (CLAUDE.md) - Standards and patterns for contributors using Claude Code
• AI Agent Instructions (AGENTS.md) - Guide for general AI coding assistants (Cursor, Continue, Aider, etc.)
• GitHub Copilot Guidelines - Best practices for using GitHub Copilot responsibly in this project

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:

• Geocoding tools: Address/location text, coordinates, country/region filters
• Search tools: Search queries, location coordinates for proximity, category filters
• Directions tool: Start/end coordinates, waypoints, routing preferences, vehicle constraints
• Matrix tool: Multiple coordinate pairs, travel profile, departure times
• Static map tool: Coordinates, zoom level, styling preferences, marker information
• Isochrone tool: Origin coordinates, time/distance parameters, travel profile

Your privacy

• Local execution: All API calls are made directly from your environment to Mapbox APIs
• Token security: Your Mapbox API token remains on your local machine and is never transmitted to or stored by this MCP server
• No data storage: This MCP server does not store, log, or collect any of your data or API requests
• Direct communication: There is no intermediary server between you and Mapbox APIs

Third - party data usage

• Mapbox's privacy policy governs data sent to their APIs: https://www.mapbox.com/legal/privacy/
• API usage: Standard Mapbox API terms apply to all requests made through these tools
• Data retention: Refer to Mapbox's documentation for their data retention policies

📞 Support & Contact

For MCP Server Issues

• Email: mcp - feedback@mapbox.com
• GitHub Issues: Report bugs and feature requests

For Mapbox API Questions

• Mapbox Support: https://support.mapbox.com/
• Documentation: https://docs.mapbox.com/
• API Status: https://status.mapbox.com/

Maintenance Commitment

This MCP server is officially maintained by Mapbox, Inc. We provide regular updates for new Mapbox API features, bug fixes and security updates, compatibility with latest MCP protocol versions, and community support through GitHub issues.

📄 License

MIT License