MCP Server | API Docs

The Mapbox MCP Server exposes Mapbox web services APIs in the Model Context Protocol, an open standard for AI tools to connect with external services. You can run the MCP Server locally or deploy it to a cloud service, and it can be used with any AI model that supports the Model Context Protocol.

Installation

Requirements:

Node.js LTS or later is required to build and run the MCP Server.

A Mapbox Access Token is required

You will need a Mapbox Access Token to use the MCP Server. An access token associates your use of Mapbox Services with your account. If you don't have one, you can create a free account, then copy your access token from the Access Tokens page.

Use the Mapbox MCP Server

The Mapbox MCP Server can be used in several ways:

Option 1: Hosted Endpoint
Option 2: Quick Start with npm
Option 3: Local Deployment

Hosted Endpoint

For the simplest setup, you can connect directly to Mapbox's hosted MCP endpoint without installing or running anything locally. This endpoint is available at https://mcp.mapbox.com/mcp.

For example, Claude Desktop users can configure the hosted endpoint by adding the mcpServers key to their claude_desktop_config.json file:


{
  "mcpServers": {
    "MapboxServer": {
      "url": "https://mcp.mapbox.com/mcp",
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

This hosted option eliminates the need for Node.js installation or local builds, making it ideal for quick setup and testing.

Quick Start with `npm`

You must configure consuming applications to connect to the Mapbox MCP Server. This typically involves referencing the MCP Server’s NPM package via npx and setting your Mapbox Access Token as an environment variable.

For example, Claude Desktop users can configure MCP servers by adding the mcpServers key to their claude_desktop_config.json file:


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

Note

If you use a Node version manager like fnm or nvm to manage multiple versions of Node.js, Claude may not automatically resolve the correct version when launching the MCP Server via npx.

To make sure the server runs using the same Node.js version as npx, you should explicitly specify the full path to the node executable in the command field.

First, find your Node.js installation path by running this in your terminal (after activating your desired Node version):

On macOS/Linux:


which node
which npx

On Windows (PowerShell):


(Get-Command node).Path
(Get-Command npx).Path

On Windows (Command Prompt):


where node
where npx

Then use those paths in your configuration. For example:


{
  "mcpServers": {
    "MapboxServer": {
      "command": "/Users/your-username/.local/state/fnm_multishells/12345_1234567890123/bin/node",
      "args": ["/Users/your-username/.npm/_npx/1234567890/node_modules/.bin/npx", "-y", "@mapbox/mcp-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

Note

The exact paths will vary depending on your system and version manager. Use the output from which node and which npx to find your actual paths.

Consult the documentation of your AI model or application for specific instructions on how to configure MCP servers.

Installation guides are available for the following applications in the public repository:

Local Deployment

To use Mapbox MCP Server with local Node.js involves two main steps:

Clone the MCP Server code repository and build the project.
Configure a consuming application to run and connect to the MCP Server, providing your Mapbox Access Token.

Clone and build the MCP Server

Clone the repository:


$git clone https://github.com/mapbox/mcp-server.git

Change into the project directory:


$cd mcp-server

Install dependencies:


$npm install

Build the project:


$npm run build

The built MCP Server will be located in the dist directory in two formats:

dist/esm/index.js for ESM (ECMAScript Module) support
dist/commonjs/index.js for CommonJS support

You will need to reference one of these locations when configuring consuming applications. Use the ESM version unless you have specific CommonJS requirements.

Docker Configuration

You may also build and run the MCP Server using Docker. See the Dockerfile in the project repository.

Configure the consuming application

You must configure consuming applications to connect to the Mapbox MCP Server. This typically involves specifying the path to the MCP Server node.js file and providing your Mapbox Access Token as an environment variable.

For example, Claude Desktop users can configure MCP servers by adding the mcpServers key to their claude_desktop_config.json file:


{
  "mcpServers": {
    "MapboxServer": {
      "command": "node",
      "args": ["/Users/username/github-projects/mcp-server/dist/esm/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

Consult the documentation of your AI model or application for specific instructions on how to configure MCP servers.

Installation guides are available for the following applications in the public repository:

Configuration

The Mapbox MCP Server supports several configuration options to customize its behavior.

Environment Variables

MAPBOX_ACCESS_TOKEN (required): Your Mapbox access token for authenticating API requests.
ENABLE_MCP_UI (optional): Toggle MCP-UI support for interactive features. Defaults to enabled. Set to false to disable.

Command-Line Flags

When running the server locally, you can use the following command-line flags:

--disable-mcp-ui: Disable interactive UI rendering features.

MCP-UI Support

The Mapbox MCP Server provides interactive UI capabilities for compatible clients through MCP-UI:

Static Map Tool: Returns both image data and embeddable iframe URLs for interactive viewing
Backward Compatible: Clients that don't support MCP-UI will still receive standard output
Default Enabled: MCP-UI features are enabled by default with no configuration required

To disable MCP-UI features, set the ENABLE_MCP_UI environment variable to false or use the --disable-mcp-ui command-line flag.

Resources

The Mapbox MCP Server provides access to static reference data through MCP Resources. Clients can access these resources using the following URIs:

mapbox://categories - Default category list for POI searches
mapbox://categories/{language} - Localized category lists (e.g., mapbox://categories/ja for Japanese, mapbox://categories/es for Spanish)

These resources can be used to understand available POI categories and their localized names when constructing search queries.

Tools

The Mapbox MCP Server provides the following tools, which provide various geographic services such as searching for places, calculating routes, and generating maps. Each tool is powered by a specific Mapbox Web Services API, and you can use them to enhance your AI-powered applications with geographic capabilities.

Tool	Description
`ResourceReaderTool`	Accesses static reference data and category lists through MCP Resources (e.g., `mapbox://categories`). Useful for retrieving available POI categories and localized category names.
`CategorySearchTool`	Searches for geographic categories such as countries, regions, or postal codes. Useful for narrowing down search queries to a specific type of place. Powered by the Search Box API
`DirectionsTool`	Calculates optimal routes between waypoints for driving, walking, or cycling. Powered by the Directions API.
`ForwardGeocodeTool`	Converts a place name or address into geographic coordinates. Powered by the Geocoding API – Forward Geocoding.
`IsochroneTool`	Calculates areas reachable within a specified travel time from a location. Powered by the Isochrone API.
`MatrixTool`	Computes travel times and distances between multiple points. Ideal for optimizing logistics. Powered by the Matrix API.
`POISearchTool`	Finds points of interest such as restaurants, gas stations, or landmarks near a given location. Powered by the Search Box API.
`ReverseGeocodeTool`	Converts geographic coordinates into a readable address or place name. Powered by the Geocoding API – Reverse Geocoding.
`StaticMapTool`	Provides static map images of a specified location and zoom level with marker, circle, line, and polygon data overlays. Powered by the Static Images API.

このpageは役に立ちましたか？

Mapbox MCP Server

Installation​

Use the Mapbox MCP Server​

Hosted Endpoint​

Quick Start with npm​

Local Deployment​

Clone and build the MCP Server​

Configure the consuming application​

Configuration​

Environment Variables​

Command-Line Flags​

MCP-UI Support​

Resources​

Tools​