DOCSEARCHbyAlgolia
Submit Docs

Mapbox MCP Server

repository·main·Indexed 43 days ago

https://github.com/mapbox/mcp-server

A Node.js implementation of the Model Context Protocol (MCP) that provides AI agents with geospatial intelligence. It enables tasks such as geocoding, POI search, routing, and interactive map visualization via Mapbox APIs, as well as offline geospatial calculations using Turf.js. Version 0.14.0 supports integration with clients like Claude Desktop, VS Code, Cursor AI, and smolagents.

Tokens
38K
Snippets
96
Records
146
Agent score
56%

What's inside Mapbox MCP Server

  1. Use MCP-UI for interactive maps in Goose

    main

    Goose supports MCP-UI, which enables inline interactive maps to be rendered directly in the chat interface when using the static_map_image_tool. This provides a visual experience beyond simple static images.

    If you wish to disable this feature, add the --disable-mcp-ui flag to the server arguments in your profiles.yaml:

    args:
  - '-y'
  - '@mapbox/mcp-server'
  - '--disable-mcp-ui'

  2. Understand Trace Context Propagation

    main

    The Mapbox MCP Server implements trace context propagation to ensure that observability spans are connected from the moment an MCP tool is executed through to the underlying HTTP requests made to Mapbox APIs. This creates a hierarchical trace structure that allows you to see the relationship between tool business logic and network activity.

    Trace Hierarchy Example:

    • MCP Tool Execution Span (Root)
      • Tool Business Logic
      • HTTP Request Span (Child)
        • Network Request
        • Response Processing

  3. Production tracing considerations

    main

    When using OpenTelemetry in production environments, consider the following:

    • Performance: Tracing adds <1% CPU overhead.
    • Network: Each trace is approximately 1-5KB sent to the OTLP endpoint.
    • Sampling: For high-volume environments, use sampling to reduce load. Set OTEL_TRACES_SAMPLER=traceidratio and OTEL_TRACES_SAMPLER_ARG=0.1 (for 10% sampling).
    • Security: Traces include metadata (tool names, HTTP status, input/output sizes) but do not include sensitive input data.

  4. Understand MCP-UI support in Claude Desktop

    main

    Claude Desktop does not currently support the MCP-UI specification for embedded interactive elements (like iframes).

    Behavior for Map Tools:

    • Supported: Tools like static_map_image_tool will return Base64-encoded map images which Claude can display.
    • Not Supported: Interactive iframe embeds are not supported in Claude Desktop.

    The server remains backwards compatible; all tools function normally, but you will receive static images instead of interactive maps. If you require interactive MCP-UI features, consider using Goose.

  5. Visualize geospatial data with `render_map_tool`

    main

    The render_map_tool is the server's primary visualization primitive. It uses the MCP Apps protocol (@modelcontextprotocol/ext-apps) to render a live, interactive Mapbox GL JS map directly inside supported chat clients (Claude Desktop, VS Code with GitHub Copilot, Claude Code, and Goose).

    Key Features:

    • Standalone Usage: You can render your own custom GeoJSON (polygons, markers, routes) without calling any other Mapbox tools.
    • Interactive: Supports a Fullscreen toggle within the chat interface.
    • Fallback: If your client does not support MCP Apps, use static_map_image_tool instead to receive a base64-encoded PNG/JPEG image.

  6. Perform offline geospatial calculations with Offline Geospatial Tools

    main

    The Mapbox MCP Server includes a suite of tools that perform geospatial computations entirely offline using Turf.js. These tools do not require Mapbox API calls and work without internet connectivity. They are ideal for geometric analysis, distance measurements, and spatial logic.

    Available Offline Tools:

    • Distance Tool: Calculates the distance between two coordinates using the Haversine formula. Supports units like kilometers, miles, meters, feet, and nautical miles.
    • Points Within Polygon Tool: Tests points against a polygon or multipolygon (including those with holes) to see if they are inside. Supports batch-testing.
    • Destination Tool: Calculates a destination point based on a starting point, bearing, and distance using geodesic (great-circle) offset.
    • Bearing Tool: Returns the compass direction (0-360°) and cardinal direction (e.g., N, NE, E) between two coordinates.
    • Midpoint Tool: Finds the true geographic midpoint between two coordinates on Earth's curved surface.
    • Centroid Tool: Calculates the geometric center (arithmetic mean) of a polygon or multipolygon.
    • Area Tool: Calculates the area of a polygon in units such as square meters, square kilometers, acres, hectares, square miles, or square feet.
    • Bounding Box Tool: Returns the [minLongitude, minLatitude, maxLongitude, maxLatitude] that contains a geometry (points, lines, polygons, etc.).
    • Buffer Tool: Creates a buffer zone (polygon) around a point, line, or polygon.
    • Simplify Tool: Reduces vertices in a line or polygon using the Douglas-Peucker algorithm. Supports a tolerance option and an option to maintain topology.
    • Length Tool: Measures the total length of a line in kilometers, miles, meters, or feet.
    • Convex Tool: Computes the convex hull (the smallest convex polygon containing a set of points).
    • Nearest Point Tool: Finds the nearest point in a collection to a target point.
    • Nearest Point on Line Tool: Snaps a point to the nearest position on a line/route and returns the distance.
    • Union, Intersect, and Difference Tools:
      • union_tool: Merges polygons.
      • intersect_tool: Finds shared areas.
      • difference_tool: Subtracts one polygon from another.
      • Note: These tools return a render_map_tool reference for direct visualization.

  7. Authenticate with the Mapbox Hosted MCP Server

    main

    The hosted MCP server supports two authentication methods:

    1. OAuth Flow (Interactive): Used by most MCP clients (Claude, Cursor, etc.). After configuration, a browser window will open asking you to log in to your Mapbox account and click "Allow" to grant permissions.
    2. Bearer Token (API Access): Used for programmatic/direct API access. Pass your Mapbox access token in the authorization header as Bearer <your_mapbox_access_token>.

  8. Understand the trace structure for tools and HTTP requests

    main

    The server provides automatic instrumentation for several key areas:

    Tool Execution Spans

    Traces all tool calls with attributes including:

    • tool.name: The name of the tool executed.
    • tool.input.size / tool.output.size: Payload sizes.
    • tool.success: Boolean status.
    • session.id, user.id, account.id, chat.session.id, prompt.id: Contextual identifiers.

    HTTP Request Spans

    Traces the full lifecycle of Mapbox API requests, including:

    • http.method, http.url, http.status_code.
    • CloudFront Correlation: Automatically captures x-amz-cf-id (request ID), x-amz-cf-pop (PoP location), x-cache (hit/miss), and etag for debugging and geographic analysis.

    Configuration Loading Spans

    Traces the .env loading process, capturing file existence, number of variables loaded, and success/failure status.

  9. How elicitations work in Mapbox MCP Server

    main

    Some tools in this server use the MCP elicitations feature to request user input during execution. This allows a user to manually pick between multiple search results or route options instead of the AI model choosing unilaterally.

    Implementation Details

    • Unconditional Registration: Every tool capable of elicitation is registered unconditionally. There is no pre-check for client support.
    • Graceful Fallback: Tools wrap elicitation calls in try/catch blocks. If a client does not support the MCP elicitation spec, or if the call fails, the tool falls back to its default behavior (returning all results) rather than returning an error.
    • Client Support: Support is determined by your specific MCP client. You should check your client's documentation to see if it implements the MCP elicitation specification.

  10. Data sent to Mapbox APIs

    main

    When using the MCP server tools, specific data is transmitted from your environment to Mapbox APIs. The following data types are sent depending on the tool used:

    • Geocoding tools: Address/location text, coordinates, country/region filters.
    • Search tools: Search queries, location coordinates for proximity, category filters.
    • Directions tool: Start/end coordinates, waypoints, routing preferences, vehicle constraints.
    • Matrix tool: Multiple coordinate pairs, travel profile, departure times.
    • Static map tool: Coordinates, zoom level, styling preferences, marker information.
    • Isochrone tool: Origin coordinates, time/distance parameters, travel profile.

  11. Security and Data Privacy in Tracing

    main

    The Mapbox MCP Server implements several security measures to protect sensitive data during OpenTelemetry tracing:

    • Input Sanitization: Only the sizes of inputs and outputs are logged; the actual content is never recorded.
    • Access Token Redaction: A redacting exporter automatically strips the signature from Mapbox access tokens in request URLs (e.g., url.full, url.query). Tokens following the <prefix>.<payload>.<signature> format (with pk, sk, or tk prefixes) are partially redacted to show access_token=pk.your-account.redacted. This allows for identifying the account and token type without exposing the authentication signature. Tokens that do not match this format are replaced entirely with access_token=***.
    • JWT Validation: The server performs basic format validation on JWTs but does not perform secret verification.
    • Error Messages: While error details are logged, sensitive data is protected.

    Authentication Best Practices:

    • Use OTLP headers for authenticating with your telemetry backend.
    • Always use HTTPS endpoints for production environments.
    • For AWS X-Ray integration, use IAM roles.

  12. Privacy and Data Security

    main

    The Mapbox MCP server is designed with privacy in mind:

    • Local execution: All API calls are made directly from your environment to Mapbox APIs.
    • Token security: Your MAPBOX_ACCESS_TOKEN remains on your local machine and is never transmitted to or stored by this MCP server.
    • No data storage: The server does not store, log, or collect any of your data or API requests.
    • Direct communication: There is no intermediary server between you and Mapbox APIs.