mcp

The Mapbox MCP Server exposes a Node.js implementation of the Model Context Protocol (MCP) that provides Mapbox geospatial tooling to AI agents and applications. It enables capabilities such as global geocoding, POI search, multi-modal routing, travel time matrices, route optimization, map matching, isochrone generation, static map images, and offline geospatial calculations. Clients that support MCP Apps can render an interactive map panel directly within the chat, while other clients can consume the standard MCP responses and static images. To use the server, you must supply a valid Mapbox access token and run the MCP server locally or rely on a hosted endpoint. The hosted endpoint is exposed at https://mcp.mapbox.com/mcp for quick testing, while the local server requires the MAPBOX_ACCESS_TOKEN environment variable to authorize Mapbox API calls.

Prerequisites:\n- Node.js (LTS, e.g., 18.x) and npm installed on your machine.\n- A Mapbox account to obtain an access token.\n\nInstallation steps (local development or quick start):\n1) Obtain a Mapbox access token from mapbox.com.\n2) Install or run the MCP server via npx (no local install required):\n\n - Run: npx -y @mapbox/mcp-server\n - When prompted, provide your MAPBOX_ACCESS_TOKEN through the environment variable.\n\n3) Alternative: install globally and run directly:\n\n - npm install -g @mapbox/mcp-server\n - Run: mcp-server (the CLI will use MAPBOX_ACCESS_TOKEN from your environment)\n\n4) If you prefer to run via a local project setup (optional):\n\n - Initialize a project and install the package: npm init -y && npm install @mapbox/mcp-server\n - Start the server in your codebase, ensuring MAPBOX_ACCESS_TOKEN is set in the environment.\n\n5) Verify access: Open a client and connect to the MCP endpoint. If using the hosted endpoint, use the provided URL; for local runs, point your client to http://localhost:port/mcp (default port as configured by the server).

Tips and notes:\n- An active Mapbox access token is required for all geospatial operations. Ensure token scopes include geocoding, directions, and any features you intend to use.\n- When running locally, set MAPBOX_ACCESS_TOKEN in your shell before starting the server, e.g. export MAPBOX_ACCESS_TOKEN=pk.abcdef... or set via your process manager.\n- The MCP Apps protocol allows interactive map panels in supported clients; otherwise, you will receive standard MCP responses and static map images.\n- If you encounter rate limiting, consider using a token with higher quota or enabling appropriate Mapbox services for your use case.\n- The server supports static map image generation and offline geospatial calculations; for heavy workloads, consider caching frequent queries.\n- If you deploy behind a reverse proxy, ensure proper routing to the MCP server endpoint and preserve the required headers for MCP negotiation.