Mapbox

Mapbox MCP Server

Servidor Node.js que implementa o Model Context Protocol (MCP) para as APIs Mapbox.

Desbloqueie Inteligência Geoespacial para Suas Aplicações de IA

O Mapbox MCP Server transforma qualquer agente ou aplicação de IA em um sistema com consciência geoespacial ao fornecer acesso contínuo à plataforma abrangente de inteligência de localização da Mapbox. Com este servidor, sua IA pode entender e raciocinar sobre lugares, navegar pelo mundo físico e acessar dados geoespaciais ricos, incluindo:

• Geocodificação global para converter endereços e nomes de lugares em coordenadas e vice-versa
• Busca por pontos de interesse (POI) em milhões de empresas, pontos turísticos e lugares em todo o mundo
• Roteamento multimodal para dirigir, caminhar e pedalar com tráfego em tempo real
• Matrizes de tempo de viagem para analisar acessibilidade e otimizar logística
• Otimização de rotas para encontrar a ordem de visita ideal para múltiplas paradas (problema do caixeiro viajante)
• Correspondência de mapas para ajustar rastros GPS à rede de estradas para visualização limpa de rotas
• Geração de isócronas para visualizar áreas acessíveis dentro de restrições específicas de tempo ou distância
• Renderização de mapas interativos ao vivo (render_map_tool) para exibir rotas, resultados de busca e seu próprio GeoJSON personalizado em um mapa real do Mapbox GL JS diretamente no chat
• Imagens de mapas estáticas para criar representações visuais de locais, rotas e dados geográficos
• Cálculos geoespaciais offline para distância, área, orientação, buffers e análise espacial sem exigir chamadas de API

Esteja você construindo um assistente de viagem de IA, um otimizador logístico, um recomendador baseado em localização ou qualquer aplicação que precise entender "onde", o Mapbox MCP Server fornece a inteligência espacial para tornar isso possível. Você também pode habilitá-lo em clientes populares como Claude Desktop e VS Code. Veja abaixo para detalhes

Uso

Um token de acesso à Mapbox é necessário para usar este servidor MCP.

Endpoint MCP Hospedado

Para acesso rápido, você pode usar nosso endpoint MCP hospedado:

Endpoint: https://mcp.mapbox.com/mcp

Para instruções detalhadas de configuração para diferentes clientes e uso da API, veja o Guia do Servidor MCP Hospedado.

Para obter um token de acesso à Mapbox:

1. Cadastre-se em uma conta Mapbox gratuita em mapbox.com/signup
2. Navegue até sua página de Conta
3. Crie um novo token ou use o token público padrão

Para mais informações sobre tokens de acesso da Mapbox, veja a documentação da Mapbox sobre tokens de acesso.

Guias de Integração

Para instruções detalhadas de configuração para diferentes integrações, consulte os seguintes guias:

• Configuração do Claude Desktop - Instruções para configurar o Claude Desktop para funcionar com este servidor MCP
• Configuração do Goose - Configuração do framework de agente de IA Goose
• Configuração do VS Code - Configuração de um ambiente de desenvolvimento no Visual Studio Code
• Configuração do Cursor AI IDE - Configuração de um ambiente de desenvolvimento no Cursor AI IDE
• Integração com Smolagents - Exemplo mostrando como conectar agentes de IA Smolagents às ferramentas da Mapbox
• Importando Ferramentas Diretamente - Use ferramentas Mapbox em suas próprias aplicações sem executar o servidor MCP
• Guia render_map_tool - A primitiva de visualização de mapa: esquema completo de payload e como renderizar seus próprios dados de forma independente, sem nenhuma outra ferramenta Mapbox
• Elicitações - Como search_and_geocode_tool e directions_tool pedem ao usuário para desambiguar resultados ou escolher uma rota, e como eles fazem fallback graciosamente quando o cliente não suporta isso

Exemplos de Prompts

Experimente esses prompts com o Claude Desktop ou outros clientes MCP após a configuração:

Ancoragem de Localização

Para consultas baseadas em coordenadas — "o que está perto de mim", "que bairro é este", "o que é acessível em N minutos" — use ground_location_tool. Ele compõe geocodificação reversa, busca por categoria e isócrona em uma única chamada, escolhendo adaptativamente a estratégia certa com base na consulta, e retorna registros tipados (nomes, endereços, coordenadas, distâncias, polígonos de acessibilidade) com citações.

Cada um dos quatro prompts abaixo exercita uma estratégia diferente em uma chamada de ferramenta:

• Bairro — "Que bairro é 47.6097, -122.3408, e o que está ao meu redor?"
• POI — "Cafeterias a uma curta distância a pé de 40.7580, -73.9855"
• Região — "O que posso alcançar em uma caminhada de 15 minutos a partir de 37.7749, -122.4194?"
• Roteamento — "Ponto roteável mais próximo para deixar alguém em 34.0522, -118.2437"

Descoberta de Localização

• "Encontre cafeterias a uma curta distância a pé do Empire State Building"
• "Eu quero ir de Seattle a Portland, há um Starbucks no caminho?"
• "Mostre-me postos de gasolina ao longo da rota de Boston a Nova York"
• "Quais restaurantes estão perto da Times Square?"

Navegação e Viagem

• "Obtenha direções de carro de LAX para Hollywood com tráfego atual"
• "Quanto tempo levaria para caminhar do Central Park até a Times Square?"
• "Calcule o tempo de viagem do meu hotel (Four Seasons) até o Aeroporto JFK de táxi durante a hora do rush"

Visualização e Mapas

• "Usando a ferramenta de renderização de mapa da Mapbox, mostre-me direções da Golden Gate Bridge até a Union Square em São Francisco" — renderiza uma rota interativa ao vivo em um mapa real da Mapbox
• "Crie uma imagem de mapa mostrando a rota da Golden Gate Bridge até Fisherman's Wharf com marcadores em ambos os locais"
• "Mostre-me uma vista de satélite de Manhattan com pontos turísticos principais marcados"
• "Gere um mapa destacando todas as localizações do Starbucks a um quilômetro do centro de Seattle"
• "Mostre um polígono preenchido sobre estas coordenadas: [...], com um marcador rotulado 'Armazém' em [...]" — renderiza seu próprio GeoJSON diretamente via render_map_tool, sem necessidade de outra ferramenta Mapbox

Análise e Planejamento

• "Mostre-me áreas acessíveis em 30 minutos de carro do centro de Portland"
• "Calcule uma matriz de tempo de viagem entre estas 3 localizações de hotel (Marriott, Sheraton e Hilton) e o centro de convenções em Denver"
• "Encontre a rota ideal visitando estas 3 atrações turísticas (Golden Gate, Musical Stairs e Fisherman's Wharf) em São Francisco"
• "Otimize uma rota de entrega para estes 8 endereços: [lista de endereços]"

Correspondência de GPS e Rotas

• "Limpe este rastro GPS e mostre a rota real nas estradas: [lista de coordenadas com carimbos de data/hora]"
• "Ajuste esta gravação de passeio de bicicleta à rede cicloviária: [coordenadas GPS]"
• "Corresponda esta rota de carro à rede de estradas e mostre os níveis de congestionamento de tráfego"

Cálculos Geoespaciais Offline

• "Qual é a distância em milhas entre estas duas coordenadas?"
• "Calcule a área deste polígono em quilômetros quadrados"
• "O ponto em 37.7749°N, 122.4194°W está dentro deste polígono de área de serviço?"
• "Qual é a orientação de São Francisco para Nova York?"
• "Encontre o ponto médio entre Londres e Paris"
• "Crie uma zona de amortecimento de 5 milhas ao redor desta localização"
• "Calcule o centróide deste limite de bairro"
• "Qual é a caixa delimitadora para estas coordenadas de rota?"
• "Simplifique este polígono complexo para reduzir o número de pontos"

Dicas para Melhores Resultados

• Seja específico sobre localizações (use endereços completos ou nomes de pontos turísticos)
• Especifique seu método de viagem preferido (dirigir, caminhar, pedalar)
• Inclua restrições de tempo quando relevante ("durante a hora do rush", "às 15h")
• Peça formatos de saída específicos quando necessário ("como imagem de mapa", "em formato JSON")

Exemplos detalhados: Veja examples/search-along-route.md para exemplos abrangentes do prompt de busca ao longo da rota com diferentes casos de uso e instruções de teste do MCP Inspector.

Recursos

O servidor MCP expõe dados de referência estáticos como recursos MCP. Recursos fornecem acesso somente leitura a dados que os clientes podem referenciar diretamente sem fazer chamadas de ferramenta.

Recursos Disponíveis

Recurso de Categorias Mapbox

Padrão de URI: mapbox://categories ou mapbox://categories/{language}

Acesse a lista completa de IDs de categorias disponíveis para uso com a ferramenta de busca por categoria. Categorias podem ser usadas para filtrar resultados de busca por tipo (ex.: "restaurante", "hotel", "posto_de_gasolina").

Exemplos:

• mapbox://categories - Lista de categorias padrão (inglês)
• mapbox://categories/ja - Nomes de categorias em japonês
• mapbox://categories/es - Nomes de categorias em espanhol

Acessando Recursos:

• Clientes com suporte nativo a recursos MCP: Use o método de protocolo MCP resources/read
• Clientes sem suporte a recursos: Use o resource_reader_tool com o URI do recurso

Pré-visualizações de Mapa Ricas (render_map_tool)

Toda ferramenta geoespacial neste servidor (direções, isócrona, busca e mais) pode exibir seu resultado como um mapa interativo ao vivo do Mapbox GL JS via render_map_tool — a primitiva de visualização única do servidor. Ele renderiza através do protocolo MCP Apps (@modelcontextprotocol/ext-apps) como um painel HTML independente diretamente no chat, com um botão de Tela Cheia, em clientes suportados:

• Claude Desktop ✅
• VS Code com GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Você não precisa de nenhuma outra ferramenta deste servidor para usá-lo. render_map_tool também aceita GeoJSON composto manualmente diretamente — seus próprios polígonos, marcadores e rotas — sem dependência de directions_tool, isochrone_tool ou qualquer outra chamada de API Mapbox. Veja o guia completo de render_map_tool para o esquema de payload e um exemplo independente completo.

Se você precisa de uma imagem estática garantida em clientes sem suporte a MCP Apps, use static_map_image_tool — ele retorna um PNG/JPEG codificado em base64 que todo cliente pode exibir.

CLIENT_NEEDS_RESOURCE_FALLBACK

Ferramentas de Fallback de Recursos (Opt-In para Clientes Não Conformes)

Recursos são um recurso central do MCP suportado pela maioria dos clientes (Claude Desktop, VS Code, MCP Inspector, etc.). No entanto, alguns clientes (como smolagents) não suportam recursos. Para esses clientes, o servidor pode fornecer "ferramentas de fallback de recursos" que entregam o mesmo conteúdo que os recursos, mas através de chamadas de ferramenta.

Ferramentas de Fallback:

• resource_reader_tool - Fallback genérico para ler qualquer recurso por URI
• category_list_tool - Fornece acesso à lista de categorias (mapbox://categories)

Por padrão, essas ferramentas NÃO estão incluídas (presume que seu cliente suporta recursos). Se seu cliente não suportar recursos, habilite as ferramentas de fallback:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Quando definir isso:

• ✅ Defina como true se estiver usando smolagents ou outros clientes sem suporte a recursos
• ❌ Deixe indefinido (padrão) se estiver usando Claude Desktop, VS Code, MCP Inspector ou qualquer cliente com capacidade de recursos
• ❌ Deixe indefinido se não tiver certeza (a maioria dos clientes suporta recursos)

Ferramentas

Ferramentas Utilitárias

Ferramenta de Leitura de Recursos

Fornece acesso aos recursos MCP para clientes que não suportam a API de recursos nativa do MCP. Use esta ferramenta para ler recursos como a lista de categorias.

Parâmetros:

• uri: O URI do recurso a ser lido (ex.: mapbox://categories, mapbox://categories/ja)

Exemplo de Uso:

• Ler categorias padrão: {"uri": "mapbox://categories"}
• Ler categorias em japonês: {"uri": "mapbox://categories/ja"}

Nota: Se seu cliente MCP suporta recursos nativos, prefira usar a API de recursos diretamente para melhor desempenho.

Ferramentas Geoespaciais Offline

Estas ferramentas realizam cálculos geoespaciais completamente offline sem exigir chamadas de API da Mapbox. Elas usam Turf.js para cálculos geográficos precisos e funcionam em qualquer lugar, mesmo sem conexão com a internet.

Ferramenta de Distância

Calcule a distância entre duas coordenadas geográficas usando a fórmula de Haversine.

Recursos:

• Suporta múltiplas unidades: quilômetros, milhas, metros, pés, milhas náuticas
• Cálculo preciso de distância de círculo máximo
• Não requer chamadas de API

Exemplo de Uso: "Qual é a distância entre São Francisco (37.7749°N, 122.4194°W) e Nova York (40.7128°N, 74.0060°W)?"

Ferramenta de Pontos Dentro de Polígono

Teste um ou mais pontos contra um polígono ou multipolígono, retornando apenas aqueles dentro. Lida com um único ponto ou um lote em uma única chamada.

Recursos:

• Funciona com polígonos complexos, incluindo buracos
• Suporta multipolígonos
• Testa qualquer número de pontos em lote em uma única chamada
• Útil para geofencing, validação de zonas de entrega e segmentação de clientes

Exemplo de uso: "Quais destes endereços de entrega estão dentro da nossa área de serviço?"

Ferramenta de Destino

Calcule um ponto de destino a partir de um ponto inicial, rumo e distância usando deslocamento geodésico (círculo máximo).

Funcionalidades:

• Deslocamento em linha reta, não uma rota direcionada
• Útil para "encontrar um ponto 5 km ao norte de X" ou construir deslocamentos de pesquisa
• Não requer chamadas de API

Exemplo de uso: "Qual é o ponto 10 km a nordeste da Space Needle?"

Ferramenta de Rumo

Calcule a direção da bússola (rumo) de uma coordenada para outra.

Funcionalidades:

• Retorna o rumo em graus (0-360°)
• Fornece a direção cardinal (N, NE, L, SE, S, SO, O, NO)
• Útil para navegação e consultas de direção

Exemplo de uso: "Em que direção devo ir daqui para o aeroporto?"

Ferramenta de Ponto Médio

Encontre o ponto médio geográfico entre duas coordenadas ao longo do caminho do círculo máximo.

Funcionalidades:

• Calcula o ponto médio verdadeiro na superfície curva da Terra
• Útil para sugestões de pontos de encontro
• Lida corretamente com cálculos de longa distância

Exemplo de uso: "Qual é o ponto médio entre São Francisco e Nova York?"

Ferramenta de Centróide

Calcule o centro geométrico (centróide) de um polígono ou multipolígono.

Funcionalidades:

• Funciona com formas complexas
• Retorna a média aritmética de todos os pontos
• Útil para colocar rótulos ou marcadores

Exemplo de uso: "Onde devo colocar um marcador para este limite de bairro?"

Ferramenta de Área

Calcule a área de um polígono.

Funcionalidades:

• Suporta várias unidades: metros quadrados, quilômetros quadrados, acres, hectares, milhas quadradas, pés quadrados
• Cálculo preciso de área na superfície da Terra
• Funciona com polígonos de qualquer tamanho

Exemplo de uso: "Qual é a área deste parque em acres?"

Ferramenta de Caixa Delimitadora

Calcule a caixa delimitadora mínima (bbox) que contém uma geometria.

Funcionalidades:

• Funciona com pontos, linhas, polígonos e multipolígonos
• Retorna [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Útil para cálculos de viewport e indexação espacial

Exemplo de uso: "Qual é a caixa delimitadora para esta rota?"

Ferramenta de Buffer

Crie uma zona de buffer (polígono) ao redor de um ponto, linha ou polígono.

Funcionalidades:

• Suporta várias unidades de distância
• Cria buffers circulares em torno de pontos
• Útil para análise de proximidade e criação de zonas de influência

Exemplo de uso: "Mostre-me uma zona de buffer de 5 km ao redor deste local"

Ferramenta de Simplificação

Reduza o número de vértices de uma linha ou polígono usando o algoritmo de Douglas-Peucker.

Funcionalidades:

• Tolerância configurável para nível de detalhe
• Preserva a forma geral enquanto reduz a complexidade
• Útil para reduzir tamanhos de arquivo e melhorar o desempenho de renderização
• Opção para manter a topologia (evitar auto-interseções)

Exemplo de uso: "Simplifique este limite complexo para reduzir o número de pontos"

Ferramenta de Comprimento

Meça o comprimento total de uma linha definida por uma série de coordenadas.

Funcionalidades:

• Suporta quilômetros, milhas, metros e pés
• Útil para medir uma rota desenhada, caminho ou limite sem uma chamada de API de roteamento

Exemplo de uso: "Qual é o comprimento desta trilha de caminhada?"

Ferramenta de Convexo

Calcule o envoltório convexo de um conjunto de pontos — o menor polígono convexo que contém todos eles.

Funcionalidades:

• Útil para análise de área delimitadora ou estimativa de área de cobertura
• Funciona offline sem chamadas de API

Exemplo de uso: "Qual é o menor polígono que contém todas estas localizações de lojas?"

Ferramenta de Ponto Mais Próximo

Encontre o ponto mais próximo em uma coleção a um determinado ponto alvo.

Funcionalidades:

• Mais eficiente do que chamar distance_tool para cada candidato e ordenar
• Útil para encontrar a loja, parada ou ponto de referência mais próximo de um local

Exemplo de uso: "Qual destas lojas está mais próxima da minha localização atual?"

Ferramenta de Ponto Mais Próximo em uma Linha

Ajuste um ponto à posição mais próxima em uma linha ou rota, retornando esse ponto e a distância até ele.

Funcionalidades:

• Útil para "qual ponto nesta rota está mais próximo da minha localização?" ou correspondência de mapa sem uma chamada de API

Exemplo de uso: "Onde nesta trilha de caminhada estou mais próximo agora?"

Ferramentas de União, Interseção e Diferença

Combine ou compare dois ou mais polígonos — union_tool os mescla em uma única geometria, intersect_tool encontra a área que compartilham e difference_tool subtrai um do outro.

Funcionalidades:

• Útil para combinar áreas de serviço, encontrar sobreposição de cobertura ou calcular zonas de exclusão (por exemplo, "o que é coberto pela zona A, mas não pela zona B?")
• Funciona totalmente offline — nenhuma chamada de API necessária
• Cada um retorna uma referência render_map_tool para que o resultado possa ser visualizado diretamente

Exemplo de uso: "Combine estas duas zonas de entrega em uma única área de cobertura" / "Onde estas duas isócronas se sobrepõem?" / "Qual parte desta área de serviço não é coberta pela nossa isócrona de 15 minutos?"

Ferramentas de API Mapbox

Ferramenta de Lista de Categorias (Obsoleta)

⚠️ Obsoleta: Use o resource_reader_tool com URI mapbox://categories em vez disso, ou acesse o recurso mapbox://categories diretamente se seu cliente suportar recursos MCP.

Esta ferramenta é mantida para compatibilidade retroativa com clientes que não suportam recursos MCP ou a ferramenta resource_reader_tool.

Ferramenta de Matriz

Calcula tempos de viagem e distâncias entre vários pontos usando a API Matrix do Mapbox. Funcionalidades incluem:

• Cálculos de roteamento eficientes um-para-muitos, muitos-para-um ou muitos-para-muitos
• Suporte para diferentes perfis de viagem (driving-traffic, driving, walking, cycling)
• Especificação de horário de partida para cálculos conscientes do tráfego
• Resumo de rota com métricas de distância e duração
• Controle de aproximação (curb/unrestricted) e intervalo de rumos de partida permitidos

Ferramenta de Imagem Estática

Gera imagens de mapa estáticas usando a API de imagem estática do Mapbox. Funcionalidades incluem:

• Estilos de mapa personalizados (streets, outdoors, satellite, etc.)
• Dimensões de imagem e níveis de zoom ajustáveis
• Suporte para múltiplos marcadores com cores e rótulos personalizados
• Opções de sobreposição incluindo polilinhas e polígonos
• Ajuste automático a coordenadas especificadas

Ferramenta de Pesquisa por Categoria

Realiza uma pesquisa por categoria usando a API de pesquisa por categoria do Mapbox Search Box. Funcionalidades incluem:

• Pesquisa de pontos de interesse por categoria (restaurantes, hotéis, postos de gasolina, etc.)
• Filtragem por proximidade geográfica
• Limites de resultados personalizáveis
• Metadados ricos para cada resultado
• Suporte para vários idiomas

Ferramenta de Geocodificação Reversa

Realiza geocodificação reversa usando a API de geocodificação V6 do Mapbox. Funcionalidades incluem:

• Converter coordenadas geográficas em endereços legíveis por humanos
• Níveis de detalhe personalizáveis (rua, bairro, cidade, etc.)
• Filtragem de resultados por tipo (endereço, POI, bairro, etc.)
• Suporte para vários idiomas
• Informações contextuais ricas do local

Ferramenta de Localização no Terreno

Responde perguntas "o que há perto desta coordenada" em uma única chamada — nome do local, pontos de interesse próximos e acessibilidade por tempo de viagem — obtidos de dados ao vivo do Mapbox com citações. Use esta ferramenta em vez de encadear reverse_geocode_tool com uma pesquisa na web.

Funcionalidades:

• Classifica a consulta (roteamento, contexto de bairro, pesquisa de POI ou região/acessibilidade) e busca apenas os dados relevantes
• Pesquisa de POIs próximos por categoria, quando solicitado
• Resumo de acessibilidade por tempo de viagem (baseado em isócrona)
• Retorna uma referência render_map_tool com o local fundamentado e POIs próximos plotados

Exemplo de uso: "Em que bairro esta coordenada está, e há algum café por perto?"

Ferramenta de Detalhes do Local

Recupera informações detalhadas sobre um local específico usando seu ID Mapbox — fotos, horários de funcionamento, avaliações, números de telefone e URLs de sites. Use após search_and_geocode_tool, category_search_tool ou reverse_geocode_tool para obter mais detalhes sobre um resultado específico.

Exemplo de uso: "Fale-me mais sobre aquele primeiro resultado de café — horários, número de telefone e site"

Ferramenta de Direções

Obtém instruções de rota usando a API Directions do Mapbox. Funcionalidades incluem:

• Suporte para diferentes perfis de roteamento: driving (com tráfego ao vivo ou típico), walking e cycling
• Rota de múltiplos waypoints (2-25 pares de coordenadas)
• Opção de rotas alternativas
• Anotações de rota (distância, duração, velocidade, congestionamento)
• Opções de agendamento:
  • Horário de partida futuro (depart_at) para perfis driving e driving-traffic
  • Horário de chegada desejado (arrive_by) apenas para o perfil driving
• Otimizações específicas de perfil:
  • Driving: restrições de dimensão do veículo (altura, largura, peso)
• Opções de exclusão para roteamento:
  • Exclusões comuns: balsas, pedágios somente em dinheiro
  • Exclusões específicas para driving: pedágios, autoestradas, estradas não pavimentadas, túneis, fronteiras de países, fronteiras de estados
  • Exclusões de pontos personalizados (até 50 pontos geográficos a evitar)
• Formato de saída de geometria GeoJSON

Ferramenta de Isócrona

Calcula áreas que podem ser alcançadas dentro de um período de tempo especificado a partir de um local usando a API Isochrone do Mapbox. Funcionalidades incluem:

• Suporte para diferentes perfis de viagem (driving, walking, cycling)
• Tempos de viagem ou distâncias personalizáveis
• Geração de múltiplos contornos (por exemplo, faixas de 15, 30, 45 minutos)
• Especificação opcional de horário de partida ou chegada
• Personalização de cores para visualização

Ferramenta de Pesquisa e Geocodificação

Usa o endpoint API de Pesquisa de Texto do Mapbox Search Box para alimentar a pesquisa e geocodificação de POIs, endereços, lugares e quaisquer outros tipos suportados por essa API. Esta ferramenta consolida a funcionalidade que anteriormente era fornecida pelo ForwardGeocodeTool e PoiSearchTool (de versões anteriores deste servidor MCP) em uma única ferramenta.

Ferramenta de Correspondência de Mapa

Ajusta rastros de GPS à rede viária usando a API Map Matching do Mapbox. Funcionalidades incluem:

• Converter rastros de GPS ruidosos em rotas limpas na rede viária
• Suporte para diferentes perfis de viagem (driving, driving-traffic, walking, cycling)
• Lidar com até 100 pares de coordenadas por solicitação
• Carimbos de data/hora opcionais para maior precisão baseada em velocidade
• Raios de ajuste configuráveis para diferentes níveis de qualidade de GPS
• Anotações de rota (limites de velocidade, distância, duração, congestionamento de tráfego)
• Múltiplos formatos de saída de geometria (GeoJSON, polyline)

Exemplo de uso: "Limpe este rastro de GPS e ajuste-o às estradas: [coordenadas com carimbos de data/hora]"

Ferramenta de Otimização

Encontra a rota ideal através de múltiplos locais usando a API Optimization do Mapbox. Funcionalidades incluem:

• Resolver o problema do caixeiro viajante (TSP) para 2-12 locais
• Suporte para diferentes perfis de viagem (driving, driving-traffic, walking, cycling)
• Configuração flexível de ponto inicial e final
• Otimização de viagem de ida e volta ou só ida
• Instruções de navegação passo a passo (opcional)
• Anotações de rota (distância, duração, velocidade)
• Múltiplos formatos de saída de geometria (GeoJSON, polyline)

Exemplo de uso: "Encontre a rota ideal para visitar estas 5 paradas: [lista de endereços ou coordenadas]"

Nota: Uma API V2 com recursos avançados (janelas de tempo, restrições de capacidade, múltiplos veículos) está disponível, mas requer acesso beta. A implementação V2 está incluída no código, mas não registrada por padrão.

Desenvolvimento

Inspecionando o servidor

Usando Node.js

# Run the built image
npm run inspect:build

Usando Docker

# 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

Criar nova ferramenta

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Lançando uma Nova Versão

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

Importante: O fluxo de trabalho do publicador valida que as versões package.json e server.json correspondem à versão do lançamento. Pular o incremento de versão ou a sincronização do manifesto causará falhas de publicação.

Rastreamento OpenTelemetry

Este servidor MCP inclui rastreamento abrangente OpenTelemetry para observabilidade em produção:

Demonstração Rápida

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

Nota: O servidor carrega automaticamente a configuração do seu arquivo .env na inicialização. O arquivo .env.example inclui exemplos de configuração para múltiplas plataformas de observabilidade.

Plataformas de Observabilidade Suportadas

Exemplos de configuração incluídos em .env.example para:

Provedores de Nuvem:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

Plataformas SaaS:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Any OTLP-compatible backend

Configuração de Produção

Consulte docs/tracing.md para obter instruções completas de configuração, incluindo:

• 🔧 Guias de configuração específicos da plataforma
• 📊 Configuração de autenticação e endpoint
• 🎯 Atributos e contexto de rastreamento personalizados
• 🚀 Otimização de desempenho (overhead mínimo)
• 🔍 Solução de problemas e depuração

Funcionalidades de Rastreamento:

• ✅ Rastreamento de carregamento de configuração (carregamento de arquivo .env)
• ✅ Rastreamento automático de execução de ferramentas
• ✅ Instrumentação de requisições HTTP com IDs de correlação do CloudFront
• ✅ Exportadores configuráveis (console, OTLP)
• ✅ Consciente de segurança (proteção de dados, validação JWT)
• ✅ Pronto para produção (overhead de CPU <1%)

Contribuindo

Aceitamos contribuições para o Mapbox MCP Server! Leia CONTRIBUTING.md antes de enviar um pull request.

Padrões e diretrizes completos:

• CONTRIBUTING.md - Primeiros passos, processo de PR, referência rápida
• Padrões de Engenharia (docs/engineering_standards.md) - Padrões completos de qualidade de código, testes, documentação e colaboração
• Guia Claude Code (CLAUDE.md) - Padrões e diretrizes para contribuidores que usam Claude Code
• Instruções para Agentes de IA (AGENTS.md) - Guia para outros assistentes de codificação de IA (Cursor, Continue, Aider, etc.)
• Diretrizes do GitHub Copilot - Melhores práticas para usar o GitHub Copilot de forma responsável

Início Rápido para Contribuidores

1. Faça um fork do repositório e clone o seu fork
2. Instale as dependências: npm install
3. Faça suas alterações seguindo nossos padrões de codificação
4. Execute testes e linting: npm test && npm run lint
5. Adicione testes para qualquer nova funcionalidade
6. Envie um pull request com uma descrição clara

Todas as contribuições devem passar por nossas verificações de CI e processo de revisão de código. Consulte docs/engineering_standards.md para requisitos detalhados.

Uso de Dados e Privacidade

Quais dados são enviados para as APIs do Mapbox

Ao usar as ferramentas do servidor MCP, os seguintes dados são enviados diretamente do seu ambiente para as APIs do Mapbox:

• Ferramentas de geocodificação: Texto de endereço/localização, coordenadas, filtros de país/região
• Ferramentas de pesquisa: Consultas de pesquisa, coordenadas de localização para proximidade, filtros de categoria
• Ferramenta de direções: Coordenadas de início/fim, waypoints, preferências de rota, restrições de veículo
• Ferramenta de matriz: Múltiplos pares de coordenadas, perfil de viagem, horários de partida
• Ferramenta de mapa estático: Coordenadas, nível de zoom, preferências de estilo, informações de marcadores
• Ferramenta de isócrona: Coordenadas de origem, parâmetros de tempo/distância, perfil de viagem

Sua privacidade

• Execução local: Todas as chamadas de API são feitas diretamente do seu ambiente para as APIs do Mapbox
• Segurança do token: Seu token da API Mapbox permanece em sua máquina local e nunca é transmitido ou armazenado por este servidor MCP
• Sem armazenamento de dados: Este servidor MCP não armazena, registra ou coleta nenhum dos seus dados ou requisições de API
• Comunicação direta: Não há servidor intermediário entre você e as APIs do Mapbox

Uso de dados de terceiros

• A política de privacidade do Mapbox rege os dados enviados às suas APIs: https://www.mapbox.com/legal/privacy/
• Uso da API: Os termos padrão da API Mapbox se aplicam a todas as requisições feitas por meio dessas ferramentas
• Retenção de dados: Consulte a documentação do Mapbox para suas políticas de retenção de dados

Suporte e Contato

Para Problemas com o Servidor MCP

• Email: mcp-feedback@mapbox.com
• GitHub Issues: Relatar bugs e solicitar funcionalidades

Para Perguntas sobre a API Mapbox

• Mapbox Support: https://support.mapbox.com/
• Documentation: https://docs.mapbox.com/
• API Status: https://status.mapbox.com/

Compromisso de Manutenção

Este servidor MCP é oficialmente mantido pela Mapbox, Inc. Nós fornecemos:

• Atualizações regulares para novos recursos da API Mapbox
• Correções de bugs e atualizações de segurança
• Compatibilidade com as versões mais recentes do protocolo MCP
• Suporte da comunidade através de issues no GitHub

---

MIT License