mcp-server

Mapbox MCP Server is a Node.js server that implements the Model Context Protocol (MCP) to connect the geospatial capabilities of the Mapbox API to AI agents and applications. Its official positioning is to turn any AI agent or application into a system with geospatial awareness, enabling it to understand and reason about places, navigate the physical world, and access rich geospatial data.

Main capabilities

• Global geocoding: Convert addresses and place names into coordinates, or vice versa.
• Points of interest (POI) search: Covering millions of businesses, landmarks, and places worldwide.
• Multimodal route planning: Supports driving, walking, and cycling, and includes real-time traffic.
• Travel time matrix: Used to analyze reachability and optimize logistics.
• Route optimization: Find the optimal order of visits for multiple stops (traveling salesman problem).
• Map matching: Fit GPS traces to the road network to facilitate clear route visualization.
• Isochrone generation: Visualize areas reachable within a specific time or distance constraint.
• Real-time interactive map rendering (render_map_tool): Display routes, search results, and custom GeoJSON directly on a real Mapbox GL JS map in chat.
• Static map images: Generate visual representations of places, routes, and geographic data.
• Offline geospatial computation: Distance, area, bearing, buffers, and spatial analysis without API calls.

Usage and integration

• Using this MCP server requires a Mapbox access token. How to obtain it: Sign up for a free Mapbox account at mapbox.com/signup, go to the account page, create a new token, or use the default public token.
• Provided hosted MCP endpoint:https://mcp.mapbox.com/mcp , you can refer to the Hosted MCP Server Guide for setup in different clients.
• Integration guides include: Claude Desktop setup, Goose setup, VS Code setup, Cursor AI IDE setup, Smolagents integration, and direct tool import (without running the MCP server).
• A render_map_tool guide is also provided, explaining the complete payload structure of the map visualization primitive and how to independently render your own data.

Resources and fallback mechanism

• The server exposes static reference data as MCP resources, with the URI pattern mapbox://categories or mapbox://categories/{language}, allowing retrieval of the complete list of category IDs used for category search, such as the default English list, Japanese (mapbox://categories/ja), and Spanish (mapbox://categories/es).
• Clients that support native MCP resources can use the resources/read method; clients that do not support resource support (such as smolagents) can enable "resource fallback tools," including resource_reader_tool and category_list_tool. These tools are not included by default and are enabled only when the client does not support resources.

Map visualization

• render_map_tool is the server's only visualization primitive. It renders directly in chat as a self-contained HTML panel through the MCP Apps protocol (@modelcontextprotocol/ext-apps), with full-screen toggle, and supports Claude Desktop and VS Code with GitHub Copilot. It can also directly accept hand-written GeoJSON without relying on other Mapbox API calls.
• Clients that do not support MCP Apps can use static_map_image_tool, which returns a base64-encoded PNG/JPEG.
• export_map_html_tool is used when an agent builds a web page or file to return a standalone HTML map page. It has the same input as render_map_tool and returns a packageA few-KB document containing map data and a Mapbox public token, which can be saved as map.html or embedded via iframe. Map data per page is limited to 200 KB; large polygons must first be simplified with simplify_tool. Pages use the account's default public token by default unless public_token is passed; published sites should use a URL-restricted public token. The map script is loaded from jsDelivr and pinned by version and subresource integrity hash. Live layers (routes, isochrones, search results) are fetched from the Mapbox API on each page load and count toward billing for the account that owns the token.

Offline geospatial tools

Built on Turf.js, they run entirely offline, require no Mapbox API calls, and support environments without network access: distance calculation (Haversine formula, supporting kilometers, miles, meters, feet, nautical miles), point-in-polygon or point-in-multipolygon testing (supporting holes and batch testing, for geofencing, delivery area validation, and customer segmentation), calculating a destination point given a start point, bearing, and distance (geodesic offset, not routing), bearing calculation (returning 0-360 degrees and cardinal directions), great-circle midpoint between two points, polygon centroid, and polygon area (supporting square meters, square kilometers, acres, hectares, etc.).

Use cases

They can be used to build AI travel assistants, logistics optimizers, location-based recommenders, or any application that needs to understand "where." Example prompts cover location lookup, place discovery, navigation and travel, visualization and maps, analysis and planning, GPS and route matching, offline geospatial computation, and more.

Limitations and notes

• A Mapbox access token must be obtained before use.
• The rich map preview of render_map_tool is only available in clients that support the MCP Apps protocol (such as Claude Desktop and VS Code with GitHub Copilot).
• export_map_html_tool limits map data to 200 KB per page; large polygons must first be simplified with simplify_tool.
• The offline tools perform straight-line geodesic calculations, not actual route planning.
• For more client setup, API usage, and complete examples, refer to the official integration guides.