DEV Community: Matthew Podwysocki

Introducing Mapbox Agent Skills

Matthew Podwysocki — Wed, 11 Feb 2026 22:09:57 +0000

I'm excited to share something we've been working on that makes building with Mapbox a lot easier, especially if you're using AI coding assistants like Claude Code, Cursor, or GitHub Copilot.

We've built a collection of Agent Skills that teach AI assistants how to build better Mapbox applications. Think of it as giving your AI assistant a crash course in Mapbox development best practices.

TL;DR

Agent Skills teach AI assistants Mapbox development best practices. We've built 15 skills and counting covering web/iOS/Android integration, performance optimization, search implementation, geospatial operations, map design, migrations, security, and common patterns. Install them and your AI will know things like "cluster 1000+ markers" and "use Search Box API for autocomplete."

Install all skills:

npx add-skill mapbox/mapbox-agent-skills

Install specific skills:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

List available skills:

npx skills add mapbox/mapbox-agent-skills --list

What Are Skills?

If you've been using AI coding assistants, you've probably noticed they're pretty good at writing code, but sometimes they miss the nuances. They might suggest patterns that work but aren't optimal, or miss important details about how things should be done.

Agent Skills are a way to fix this. They're folders with instructions and guidance that AI assistants can load and use when helping you build. Unlike tools (which let AI do things) or prompts (which give specific instructions), skills provide domain expertise. The know-how.

When an AI assistant has access to Mapbox skills, it knows things like "if you're adding 1000+ markers, you should use clustering" or "use the Search Box API for autocomplete, not the Geocoding API." It's the difference between an AI that knows how to code and one that knows how to code Mapbox apps specifically.

See It In Action

This production-ready store locator was built in minutes using Claude Code with Mapbox Agent Skills. The AI assistant handled marker patterns, distance calculations, search functionality, and responsive design automatically—following Mapbox best practices from the start.

Why Skills Are Important

Here's the thing: Mapbox has a lot of surface area. We have SDKs for web, iOS, and Android. We have multiple search APIs with different use cases. We have performance patterns that matter at scale. We have migration paths from other platforms.

When you're building with an AI assistant, you want it to know all this stuff. You don't want to spend time correcting it when it suggests using 1000 individual markers instead of clustering. You don't want it to miss that you should debounce search requests. You want it to just know.

That's what these skills do. They encode the knowledge we've built up from working with thousands of developers building Mapbox applications. The patterns that work. The mistakes to avoid. The right tool for the job.

What's Inside the Box

We've organized the skills into a few main areas. Here's what's available:

Platform Integration

Web, iOS, and Android patterns - These skills cover the fundamentals of integrating Mapbox into your app, whether you're building for the web with React, Vue, Svelte, or Angular, or going native with Swift/SwiftUI on iOS or Kotlin/Jetpack Compose on Android. They know about framework-specific patterns, lifecycle management, and platform best practices.

Performance

Web performance patterns - This one's huge. It covers everything from initialization strategies to handling thousands of markers, optimizing data loading, and managing memory. If you're building something that needs to perform at scale, this skill will save you a lot of debugging time.

Search

Search integration and patterns - We have two skills here. One walks through the complete workflow of adding search to your app (asking the right discovery questions, picking the right product, implementing it correctly). The other helps you choose between our different search tools and configure them properly. Between these two, your AI assistant will know exactly how to implement search for your use case.

Geospatial Operations

Geometric calculations and routing - This skill helps decide when to use offline geometric calculations (like measuring straight-line distance) versus when to use our routing APIs (like getting actual drive times). It's the "as the crow flies vs as the crow drives" decision framework, plus a ton of practical examples.

Design and Cartography

Map design, styles, and quality - Three skills covering cartographic principles (color theory, visual hierarchy, typography), common style patterns and layer configurations, and style validation and optimization. If you're doing custom map design, these will help you make maps that look professional and work well.

Migration

Google Maps and MapLibre migration - If you're moving from Google Maps Platform or MapLibre, these skills provide comprehensive migration guides with API equivalents and pattern translations. They know the gotchas and the breaking changes.

Security

Token security - Best practices for handling access tokens securely across all platforms. This is one of those things that's easy to get wrong, so having your AI assistant know the right patterns from the start is valuable.

Common Patterns

Store locators - A focused skill on building location finders and store locators, with patterns for markers, filtering, distance calculations, and all the UX details that make these features work well.

Getting Started

Installing skills is straightforward. If you're using Claude Code, Cursor, or another AI assistant that supports Agent Skills, you can add them all at once:

npx skills add mapbox/mapbox-agent-skills

Or install specific skills if you only need certain ones:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

You can list what's available:

npx skills add mapbox/mapbox-agent-skills --list

Once installed, your AI assistant will automatically use these skills when you're working on Mapbox projects. You don't need to do anything special. Just start building and you'll notice better suggestions, fewer mistakes, and more production-ready code.

Pro tip: These skills work great with our Mapbox MCP servers. We have the Mapbox MCP Server for core Mapbox operations and the Mapbox MCP DevKit Server for development workflows. Skills provide the expertise (how to design good maps, which patterns to use), while MCP tools provide the actions (create styles, generate tokens, preview maps). Together they make a pretty powerful development workflow.

Build Stuff and Let Us Know

We built these skills based on what we've learned from years of working with developers building Mapbox applications. But they'll get better as more people use them and give us feedback.

If you build something cool with these skills, or if you find gaps where your AI assistant could use more guidance, let us know. Open an issue on GitHub or contribute a new skill if you've discovered patterns we should capture.

We're excited to see what you build.

Introducing the Mapbox MCP Server: Location Intelligence for AI Agents

Matthew Podwysocki — Tue, 16 Dec 2025 14:43:34 +0000

AI agents are getting smarter every day as they can write code, analyze data, and answer complex questions. But when it comes to understanding where things are, most agents hit a wall. They can tell you about restaurants in San Francisco, but they can't geocode an address, calculate a route, or determine if two locations are within walking distance.

That's where the Mapbox Model Context Protocol (MCP) Server comes in. It gives AI agents access to Mapbox's powerful location services through a simple, standardized interface. No custom API integration required, just connect your agent to the MCP server, and it can instantly geocode addresses, plan routes, analyze travel times, and create maps.

Example: An AI agent built with MCP can naturally handle location queries and display results visually

What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard created by Anthropic for connecting AI models to external tools and data sources. Think of it as USB for AI agents which is to say a universal connector that works across different frameworks and platforms.

Instead of writing custom code to integrate with each API, you:

Connect your agent to an MCP server
The server exposes its tools in a standardized format
Your agent can discover and use those tools automatically

MCP is supported by popular frameworks like CrewAI, LangGraph, Pydantic AI, and Mastra, as well as by AI assistants like GitHub Copilot and Claude Desktop.

What Does the Mapbox MCP Server Provide?

The Mapbox MCP Server exposes nine powerful geospatial tools that give your agents comprehensive location intelligence.

Note: Mapbox also offers the DevKit MCP Server (hosted at https://mcp-devkit.mapbox.com/mcp), which is designed to help developers build Mapbox applications by providing code examples, documentation search, and development assistance. This post focuses on the main MCP server for location intelligence. We'll cover the DevKit in a future post.

Core Tools

Tool	Purpose	Example Use
search_and_geocode_tool	Convert addresses/places to coordinates	"Find coordinates for '1600 Pennsylvania Ave, Washington DC'"
reverse_geocoding_tool	Convert coordinates to addresses	"What's the address at 38.8977, -77.0365?"
directions_tool	Calculate routes between points	"Driving directions from Boston to New York with traffic"
matrix_tool	Travel times between multiple points	"Calculate delivery times from 3 warehouses to 10 addresses"
isochrone_tool	Areas reachable within time/distance	"Show everywhere I can drive in 30 minutes from downtown"
static_image_tool	Generate map images	"Create a map showing my delivery route"
category_search_tool	Find POIs by category	"Find all museums near Central Park"
resource_reader_tool	Access reference data	"Get list of available POI categories"

What Makes These Tools Special

Unified Search & Geocoding: The search_and_geocode_tool consolidates forward geocoding and POI search into one powerful tool. It handles everything from "123 Main St" to "Starbucks near Times Square" to "Eiffel Tower."

Traffic-Aware Routing: The directions_tool supports real-time traffic data, alternative routes, and can optimize for different transportation modes (driving, walking, cycling).

Multi-Point Optimization: The matrix_tool efficiently calculates travel times between dozens of locations which is essential for logistics, delivery planning, and service area analysis.

Reachability Analysis: The isochrone_tool generates polygons showing areas reachable within specific time or distance thresholds which is perfect for analyzing coverage areas, commute zones, or delivery ranges.

Visual Output: The static_image_tool creates customizable map images with markers, routes, and overlays which is great for reports, notifications, or sharing with users.

Getting Started: Setup Options

You have two ways to use the Mapbox MCP Server:

Option 1: Hosted Server (Easiest to Get Started)

Mapbox provides a hosted MCP endpoint at https://mcp.mapbox.com/mcp that's always available with no installation required!

Authentication:

Interactive clients (Claude Desktop, VS Code): Uses OAuth flow with browser-based login
Programmatic access: Uses Bearer token authentication with your Mapbox access token

Setup:

For interactive tools like Claude Desktop, VS Code, or Cursor, add this to your MCP settings (typically in settings.json or similar config file):

{
  "mcpServers": {
    "mapbox": {
      "url": "https://mcp.mapbox.com/mcp"
    }
  }
}

For Claude Desktop specifically, the config file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

The first time you connect, a browser window will open asking you to log in to your Mapbox account and authorize access via OAuth.

For programmatic access (like in agent frameworks), you'll need:

A Mapbox account (free tier available) - Sign up here
Your Mapbox access token from your account dashboard

Then use Bearer token authentication in your code (see framework-specific tutorials for examples).

Check the Hosted MCP Server Guide for detailed setup instructions for different clients.

Pros:

No local setup or dependencies required
Managed infrastructure by Mapbox
Always available
Automatic updates
Perfect for getting started quickly

Cons:

Additional network hop (your machine → hosted MCP → Mapbox APIs)
Requires stable internet connection
Less control over configuration

Option 2: Local Server (For Development & Customization)

Run the MCP server as a local process on your machine. This gives you full control and is ideal for development, debugging, or customization.

Prerequisites:

Node.js LTS+ (for npx method) OR Python 3.10+ with uv (for uvx method)
A Mapbox account (free tier available) - Sign up here
Your Mapbox access token from your account dashboard

Setup:

For interactive tools like Claude Desktop, VS Code, or Cursor, add this to your MCP settings:

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

For Claude Desktop specifically, the config file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

For command-line testing, you can run the server directly:

# Set your access token
export MAPBOX_ACCESS_TOKEN="your_token_here"

# Run with npx (recommended)
npx -y @mapbox/mcp-server

# OR run with uvx (Python users)
pip install uv
uvx mapbox-mcp

Test it with MCP Inspector:

npx @modelcontextprotocol/inspector npx -y @mapbox/mcp-server

This opens a web interface where you can explore available tools and test them interactively.

Pros:

Full control over the server process
Lower latency (direct connection to Mapbox APIs)
Works with any Mapbox token
Can customize or extend if needed
Better for development and debugging

Cons:

Requires Node.js or Python tooling
Server process management
Must ensure dependencies are installed

Example Use Cases and Prompts

Once connected, your agents can handle natural language requests like these:

Location Discovery

"Find coffee shops within walking distance of the Empire State Building"
"Show me gas stations along the route from Boston to New York"
"What restaurants are near Times Square?"

Navigation & Travel

"Get driving directions from LAX to Hollywood with current traffic"
"How long would it take to walk from Central Park to Times Square?"
"Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi"
"What's the fastest route visiting Salesforce Tower, Twitter HQ, and Uber headquarters?"

Visualization & Maps

"Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf"
"Show me a satellite view of Manhattan with key landmarks marked"
"Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"

Analysis & Planning

"Show me areas reachable within 30 minutes of downtown Portland by car"
"Calculate a travel time matrix between 3 hotel locations and the convention center"
"Find the optimal route visiting 3 tourist attractions in San Francisco"
"I'm staying at the Fairmont. Show me everywhere I can reach by walking in 15 minutes"

Behind the Scenes

When you ask: "How long does it take to drive from the Space Needle to Pike Place Market?"

The agent automatically:

Uses search_and_geocode_tool to find Space Needle coordinates
Uses search_and_geocode_tool to find Pike Place Market coordinates
Calls directions_tool with driving profile
Returns: "約 8 minutes, 1.2 miles"

No manual API calls, no coordinate formatting, no error handling as the agent figures it all out.

Supported Frameworks and Tools

The Mapbox MCP Server works with any MCP-compatible client, including:

AI Agent Frameworks

CrewAI (Python) - Multi-agent collaboration
LangGraph (Python) - Stateful agent workflows
Pydantic AI (Python) - Type-safe agent development
Mastra (TypeScript) - Production AI applications
Smolagents (Python) - Lightweight agents from Hugging Face

Development Tools

Claude Desktop - Anthropic's AI assistant
ChatGPT - OpenAI's desktop application
Gemini CLI - Google's command-line tool
VS Code - Via MCP extensions
Cursor - AI-powered IDE
Goose - Terminal-based AI assistant

Integration Approaches

Each framework has slightly different integration patterns, but they all follow the same basic flow:

Configure the MCP server connection
Add the configuration to your agent
The agent automatically discovers available tools
Use natural language to invoke tools

We'll be publishing detailed tutorials for each major framework. Stay tuned for:

CrewAI: Building multi-agent location-aware systems
Pydantic AI: Type-safe location intelligence
Smolagents: Lightweight location-enabled agents
Mastra: Production TypeScript agents with Mapbox

Key Advantages of Using MCP

No Custom API Integration: Traditional approach requires writing geocoding logic, formatting coordinates, handling errors, chaining API calls. With MCP, you just describe what you want in natural language.

Automatic Tool Discovery: The MCP server exposes its tools in a standardized format. Your agent discovers available tools automatically and no manual configuration of each tool.

Framework Agnostic: Write once, use everywhere. The same Mapbox MCP server works with CrewAI, LangGraph, GitHub Copilot, Claude Desktop, and any other MCP-compatible client.

Natural Language Interface: Agents interpret your task descriptions and choose the right tools. Say "plan a route visiting three restaurants" and the agent figures out it needs to geocode, then calculate directions, then optimize the order.

Intelligent Tool Chaining: Agents understand dependencies between tools. They know addresses must be geocoded before calculating routes, and they handle this automatically.

Real-World Applications

Travel & Hospitality

Hotel concierge bots that provide directions and local recommendations
Trip planning assistants that optimize multi-stop itineraries
Event coordinators calculating travel times for attendees

Logistics & Delivery

Route optimization for delivery fleets
Service area analysis for expansion planning
Warehouse location analysis based on customer distribution

Real Estate

Commute time calculators for property listings
School district and amenity proximity analysis
Neighborhood boundary visualization

Field Services

Technician dispatch optimization
Service area coverage analysis
Emergency response time calculations

Location-Based Marketing

Store locators with accurate directions
Coverage area mapping for service offerings
Competitive location analysis

Getting Help and Resources

Documentation

Mapbox MCP Server GitHub - Source code and documentation
Hosted MCP Server Guide - Setup for different clients
Model Context Protocol Spec - MCP standard documentation
Mapbox API Docs - Underlying API reference

Support

Email: mcp-feedback@mapbox.com
Issues: GitHub Issues
Community: Join discussions in the MCP community

Pricing and Rate Limits

The Mapbox MCP Server uses your Mapbox account and access token. Pricing follows standard Mapbox API rates:

Geocoding: 100,000 requests/month free
Directions: 5,000 requests/month free
Matrix: Counts as multiple requests (origins × destinations)
Static Maps: 50,000 requests/month free

The free tier is generous for development and small projects. For production use, check Mapbox pricing for details.

Next Steps

Ready to add location intelligence to your AI agents?

Sign up for Mapbox: Get your free access token at mapbox.com/signup
Try the MCP Inspector: Test the server and explore available tools
Pick a framework: Start with CrewAI, LangGraph, or your preferred agent framework
Build something: Check out our framework-specific tutorials (coming soon!)

In our next post, we'll dive deep into building a multi-agent travel planning system with CrewAI and Mapbox MCP, complete with working code you can run and customize.

Also coming soon: A guide to the Mapbox DevKit MCP Server, which helps AI assistants write Mapbox code by providing documentation, examples, and API guidance which is perfect for developers building Mapbox applications.

Have questions or want to share what you're building? Reach out to mcp-feedback@mapbox.com or open an issue on GitHub.