> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/api/ja/llms.txt)

# Mapbox MCP Server

現在のバージョン：`v0.12.0`  
  

-   Get driving and walking directions
    
-   Generate isochrones and static map images
    
-   Look up addresses and points of interest
    
-   Reverse geocode coordinates
    

[インストール](https://docs.mapbox.com/api/ja/api/ja/guides/mcp-server/#installation)  
  
[Githubで貢献](https://github.com/mapbox/mcp-server)

The **Mapbox MCP Server** exposes [Mapbox web services APIs](https://docs.mapbox.com/api/ja/guides/) in the [**Model Context Protocol**](https://modelcontextprotocol.io/introduction), 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](https://nodejs.org/en/about/previous-releases) or later is required to build and run the MCP Server.

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](https://www.mapbox.com/signup/), then copy your access token from the [Access Tokens page](https://console.mapbox.com/account/access-tokens/).

## 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`.

When you first connect, you will be prompted to complete an OAuth authentication flow through your browser before the MCP server becomes available. This hosted option eliminates the need for managing access tokens manually and is ideal for quick setup and testing.

Configure your AI assistant to use the hosted endpoint:

**Claude Desktop**

Title: `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mapbox-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.mapbox.com/mcp"
      ]
    }
  }
}
```

**VS Code**

Title: `mcp.json`

```json
{
  "servers": {
    "mapbox-mcp": {
      "type": "http",
      "url": "https://mcp.mapbox.com/mcp"
    }
  }
}
```

**Cursor**

Title: `mcp.json`

```json
{
  "mcpServers": {
    "mapbox-mcp": {
      "type": "http",
      "url": "https://mcp.mapbox.com/mcp"
    }
  }
}
```

**Claude Code**

```bash
$ claude mcp add --transport http mapbox-mcp https://mcp.mapbox.com/mcp
```

**Codex**

```bash
$ codex mcp add mapbox-mcp --url https://mcp.mapbox.com/mcp
```

### 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.

Configure your AI assistant to use the Mapbox MCP Server via npm:

**Claude Desktop**

Title: `claude_desktop_config.json`

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

**VS Code**

Title: `mcp.json`

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

**Cursor**

Title: `mcp.json`

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

**Claude Code**

```bash
$ claude mcp add --transport stdio MapboxServer -- npx -y @mapbox/mcp-server

# Set the required environment variable:
$ export MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN
```

**Codex**

```bash
$ codex mcp add MapboxServer --env MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN -- npx -y @mapbox/mcp-server
```

> **Note**
> 
> If you use a Node version manager like [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/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:**

```bash
which node
which npx
```

**On Windows (PowerShell):**

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

**On Windows (Command Prompt):**

```cmd
where node
where npx
```

Then use those paths in your configuration. For example:

```json
{
  "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:

-   [Claude Desktop](https://github.com/mapbox/mcp-server/blob/main/docs/claude-desktop-setup.md)
-   [VS Code with Copilot](https://github.com/mapbox/mcp-server/blob/main/docs/vscode-setup.md)
-   [Cursor](https://github.com/mapbox/mcp-server/blob/main/docs/cursor-setup.md)
-   [Goose](https://github.com/mapbox/mcp-server/blob/main/docs/goose-setup.md)
-   [Smolagents](https://github.com/mapbox/mcp-server/tree/main/docs/using-mcp-with-smolagents)

### Local Deployment

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

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

#### Clone and build the MCP Server

1.  Clone the repository:

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

2.  Change into the project directory:

```bash
$ cd mcp-server
```

3.  Install dependencies:

```bash
$ npm install
```

4.  Build the project:

```bash
$ 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.

You may also build and run the MCP Server using Docker. See the [`Dockerfile`](https://github.com/mapbox/mcp-server/blob/main/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.

Configure your AI assistant to use the local MCP Server build:

**Claude Desktop**

Title: `claude_desktop_config.json`

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

**VS Code**

Title: `mcp.json`

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

**Cursor**

Title: `mcp.json`

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

**Claude Code**

```bash
$ claude mcp add --transport stdio MapboxServer -- node /Users/username/github-projects/mcp-server/dist/esm/index.js

# Set the required environment variable:
$ export MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN
```

**Codex**

```bash
$ codex mcp add MapboxServer --env MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN -- node /Users/username/github-projects/mcp-server/dist/esm/index.js
```

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:

-   [Claude Desktop](https://github.com/mapbox/mcp-server/blob/main/docs/claude-desktop-setup.md)
-   [VS Code with Copilot](https://github.com/mapbox/mcp-server/blob/main/docs/vscode-setup.md)
-   [Cursor](https://github.com/mapbox/mcp-server/blob/main/docs/cursor-setup.md)
-   [Goose](https://github.com/mapbox/mcp-server/blob/main/docs/goose-setup.md)
-   [Smolagents](https://github.com/mapbox/mcp-server/tree/main/docs/using-mcp-with-smolagents)

## 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.
    
-   `CLIENT_NEEDS_RESOURCE_FALLBACK` (optional): Enable fallback tools for clients that don't support native MCP resources (like smolagents). Set to `true` to enable. Defaults to `false`.
    

### Command-Line Flags

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

-   `--disable-mcp-ui`: Disable interactive UI rendering features.
-   `--enable-tools=<tool_names>`: Activate only specified tools (comma-separated, case-sensitive). Example: `--enable-tools=directions_tool,isochrone_tool`
-   `--disable-tools=<tool_names>`: Remove designated tools while keeping others active (comma-separated, case-sensitive). Example: `--disable-tools=matrix_tool,optimization_tool`

When both `--enable-tools` and `--disable-tools` are provided, the enable option takes precedence.

### 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
-   **Platform Support**: Only Goose supports full interactive maps via MCP-UI. Other platforms (Claude Desktop, Visual Studio Code, Cursor) receive base64-encoded static images
-   **Progressive Enhancement**: Tools function for all clients with enhanced UI only for capable clients
-   **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. Tools are organized into categories based on their functionality.

### Offline Geospatial Tools

These tools do calculations locally without making API calls, powered by Turf.js:

| Tool | Description |
| --- | --- |
| `distance_tool` | Calculate the distance between two geographic coordinates using the Haversine formula. |
| `bearing_tool` | Determine compass direction between coordinates with cardinal directions. |
| `midpoint_tool` | Find the geographic center along the circle path between two points. |
| `centroid_tool` | Calculate geometric center of polygons for marker placement. |
| `area_tool` | Compute polygon areas in multiple units (acres, hectares, square miles, etc.). |
| `bounding_box_tool` | Generate minimum bounding rectangles containing geometries. |
| `buffer_tool` | Create proximity zones around points, lines, or polygons. |
| `simplify_tool` | Reduce polygon vertices using Douglas-Peucker algorithm while preserving shape. |
| `destination_tool` | Calculate a destination point given a starting point, bearing, and distance. Useful for computing waypoints or search offsets. |
| `length_tool` | Measure the total length of a line in kilometers, miles, meters, or feet. Useful for measuring routes or boundaries without a routing API call. |
| `convex_tool` | Compute the convex hull of a set of points — the smallest convex polygon that contains all the points. |
| `union_tool` | Merge two or more polygons into a single unified geometry. Useful for combining service areas, delivery zones, or isochrones. |
| `intersect_tool` | Find the intersection geometry of two polygons — the area they share in common. |
| `difference_tool` | Subtract one polygon from another, returning the area in the first polygon not covered by the second. |
| `nearest_point_tool` | Find the nearest point in a collection to a given target point. Useful for finding the closest store, stop, or landmark. |
| `nearest_point_on_line_tool` | Snap a point to the nearest position on a line or route. Returns the closest point on the line and the distance to it. |
| `points_within_polygon_tool` | Test one or more geographic points against a polygon, returning only those inside. Handles single or batch points. Useful for delivery zone validation and geofencing. |

### Search & Navigation Tools

Tools for finding locations, discovering places, and converting between addresses and coordinates:

| Tool | Description |
| --- | --- |
| `search_and_geocode_tool` | Uses the [Search Box API](https://docs.mapbox.com/api/ja/search/search-box/) to search for and geocode POIs, addresses, and places. |
| `category_search_tool` | Searches for geographic categories such as countries, regions, or postal codes with proximity filtering. Powered by the [Search Box API](https://docs.mapbox.com/api/ja/search/search-box/). |
| `reverse_geocode_tool` | Converts geographic coordinates into a readable address or place name with customizable detail levels. Powered by the [Geocoding API – Reverse Geocoding](https://docs.mapbox.com/api/ja/search/geocoding/#reverse-geocoding). |
| `ground_location_tool` | Answers questions about what is near a location: neighborhood context, nearby POIs by category, and travel-time reachability. Use this as the first tool when given coordinates and asked about nearby places or area summaries. |
| `place_details_tool` | Retrieves detailed information about a specific place using its Mapbox ID, including photos, opening hours, ratings, phone numbers, and website URLs. Use after `search_and_geocode_tool` or `category_search_tool` to get additional details. |
| `resource_reader_tool` | Accesses static reference data and category lists through MCP Resources (e.g., `mapbox://categories`). Only available for clients that do not support native MCP resources; enable by setting `CLIENT_NEEDS_RESOURCE_FALLBACK=true`. |

### Advanced Routing Tools

Tools for calculating routes, travel times, and accessibility:

| Tool | Description |
| --- | --- |
| `directions_tool` | Calculates optimal routes between waypoints for driving (with traffic), walking, or cycling. Supports 2-25 waypoints with alternative routes. Powered by the [Directions API](https://docs.mapbox.com/api/ja/navigation/directions/). |
| `matrix_tool` | Computes travel times and distances between multiple points. Ideal for optimizing logistics. Supports traffic-aware departures. Powered by the [Matrix API](https://docs.mapbox.com/api/ja/navigation/matrix/). |
| `isochrone_tool` | Calculates areas reachable within a specified travel time from a location. Powered by the [Isochrone API](https://docs.mapbox.com/api/ja/navigation/isochrone/). |
| `optimization_tool` | Solves traveling sales rep problems for 2-12 locations to find optimal routes. Powered by the [Optimization API](https://docs.mapbox.com/api/ja/navigation/optimization/). |
| `map_matching_tool` | Snaps GPS traces to road networks with speed and congestion data. Powered by the [Map Matching API](https://docs.mapbox.com/api/ja/navigation/map-matching/). |

### Visualization Tools

Tools for generating map images:

| Tool | Description |
| --- | --- |
| `static_map_image_tool` | Generates customizable map images with markers, polylines, polygons, and style options. Powered by the [Static Images API](https://docs.mapbox.com/api/ja/maps/static-images/). |