mcp-server

# Mapbox MCP Server Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs. **A Mapbox access token is required to use this MCP server.** To get a Mapbox access token: 1. Sign up for a free Mapbox account at [mapbox.com/signup](https://www.mapbox.com/signup/) 2. Navigate to your [Account page](https://account.mapbox.com/) 3. Create a new token or use the default public token For more information about Mapbox access tokens, see the [Mapbox documentation on access tokens](https://docs.mapbox.com/help/dive-deeper/access-tokens/). ## Integration Guides For detailed setup instructions for different integrations, refer to the following guides: - [Claude Desktop Setup](./docs/claude-desktop-setup.md) - Instructions for configuring Claude Desktop to work with this MCP server - [VS Code Setup](./docs/vscode-setup.md) - Setting up a development environment in Visual Studio Code - [SmolaGents Integration](./docs/using-mcp-with-smolagents/README.md) - Example showing how to connect SmolaGents AI agents to Mapbox's tools ## Tools ### Mapbox API tools #### Matrix tool Calculates travel times and distances between multiple points using [Mapbox Matrix API](https://www.mapbox.com/matrix-api). Features include: - Efficient one-to-many, many-to-one or many-to-many routing calculations - Support for different travel profiles (driving-traffic, driving, walking, cycling) - Departure time specification for traffic-aware calculations - Route summarization with distance and duration metrics - Control approach (curb/unrestricted) and range of allowed departure bearings #### Static image tool Generates static map images using the [Mapbox static image API](https://docs.mapbox.com/api/maps/static-images/). Features include: - Custom map styles (streets, outdoors, satellite, etc.) - Adjustable image dimensions and zoom levels - Support for multiple markers with custom colors and labels - Overlay options including polylines and polygons - Auto-fitting to specified coordinates #### POI search tool Finds specific points of interest or brand locations by name using the [Mapbox Search Box forward search API](https://docs.mapbox.com/api/search/search-box/#search-request). Features include: - Search for specific points of interest by proper name or unique brand (e.g., "Amalie Arena", "Starbucks") - Find all nearby branches of a brand (e.g., "Macy's stores near me") - Geographic proximity biasing for more relevant results - Support for multiple languages and countries #### Category search tool Performs a category search using the [Mapbox Search Box category search API](https://docs.mapbox.com/api/search/search-box/#category-search). Features include: - Search for points of interest by category (restaurants, hotels, gas stations, etc.) - Filtering by geographic proximity - Customizable result limits - Rich metadata for each result - Support for multiple languages #### Forward geocoding tool Performs forward geocoding using the [Mapbox geocoding V6 API](https://docs.mapbox.com/api/search/geocoding/#forward-geocoding-with-search-text-input). Features include: - Convert addresses or place names to geographic coordinates - Fuzzy matching for partial or misspelled inputs - Results filtering by country, region, or bounding box - Customizable result limits - Multiple language support #### Reverse geocoding tool Performs reverse geocoding using the [Mapbox geocoding V6 API](https://docs.mapbox.com/api/search/geocoding/#reverse-geocoding). Features include: - Convert geographic coordinates to human-readable addresses - Customizable levels of detail (street, neighborhood, city, etc.) - Results filtering by type (address, poi, neighborhood, etc.) - Support for multiple languages - Rich location context information #### Directions tool Fetches routing directions using the [Mapbox Directions API](https://docs.mapbox.com/api/navigation/directions/). Features include: - Support for different routing profiles: driving (with live traffic or typical), walking, and cycling - Route from multiple waypoints (2-25 coordinate pairs) - Alternative routes option - Route annotations (distance, duration, speed, congestion) - Scheduling options: - Future departure time (`depart_at`) for driving and driving-traffic profiles - Desired arrival time (`arrive_by`) for driving profile only - Profile-specific optimizations: - Walking: customizable walking speed and bias for/against walkways - Driving: vehicle dimension constraints (height, width, weight) - Exclusion options for routing: - Common exclusions: ferry routes, cash-only tolls - Driving-specific exclusions: tolls, motorways, unpaved roads, tunnels, country borders, state borders - Custom point exclusions (up to 50 geographic points to avoid) - Multiple geometry output formats (GeoJSON, polyline) #### Isochrone tool Computes areas that are reachable within a specified amount of times from a location using [Mapbox Isochrone API](https://docs.mapbox.com/api/navigation/isochrone/). Features include: - Support for different travel profiles (driving, walking, cycling) - Customizable travel times or distances - Multiple contour generation (e.g., 15, 30, 45 minute ranges) - Optional departure or arrival time specification - Color customization for visualization # Development ## Inspecting server ### Using Node.js ```sh # Build npm run build # Inspect npx @modelcontextprotocol/inspector node dist/index.js ``` ### Using Docker ```sh # 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 ``` ## Create new tool ```sh npx plop create-tool # provide tool name without suffix (e.g. Search) ``` --- [License](LICENSE.md)