Mapbox

oficial

Desbloqueie inteligência geoespacial através das APIs do Mapbox, como geocodificação, busca de POI, direções, isócronas e mais.

GitHub
370

O que você pode fazer com Mapbox MCP?

  • Geocodificar e pesquisar lugares — Converta endereços em coordenadas ou encontre pontos de interesse, como cafeterias e postos de gasolina, com search_and_geocode_tool.
  • Obter rotas — Consulte rotas de carro, a pé ou de bicicleta com informações de trânsito, alternativas e exclusões via directions_tool.
  • Encontrar áreas acessíveis — Gere polígonos de isócronas que mostram o que é possível alcançar em determinado tempo ou distância usando isochrone_tool.
  • Identificar uma coordenada — Pergunte em qual bairro fica uma coordenada, quais pontos de interesse há nas proximidades e o que é possível alcançar em uma única chamada com ground_location_tool.
  • Exibir mapas no chat — Mostre rotas, resultados de pesquisa ou GeoJSON personalizado em um mapa interativo ao vivo com render_map_tool.
  • Consultar categorias — Leia a lista de IDs de categorias em inglês, japonês ou espanhol via mapbox://categories.

Documentação

Mapbox MCP Server

npm version

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

Desbloqueie inteligência geoespacial para seus aplicativos de IA

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

  • Geocodificação global para converter endereços e nomes de lugares em coordenadas e vice-versa
  • Pesquisa de pontos de interesse (POI) entre milhões de empresas, pontos de referência e lugares no mundo todo
  • Rotas multimodais para dirigir, caminhar e pedalar com informações de trânsito em tempo real
  • Matrizes de tempo de viagem para analisar acessibilidade e otimizar a logística
  • Otimização de rotas para encontrar a ordem ideal de visita a várias paradas (problema do caixeiro-viajante)
  • Correspondência de mapas para ajustar trajetos de GPS à rede viária e obter uma visualização limpa da rota
  • Geração de isócronas para visualizar áreas alcançáveis dentro de limites específicos de tempo ou distância
  • Renderização de mapas interativos e ao vivo (render_map_tool) para exibir rotas, resultados de pesquisa e seu próprio GeoJSON personalizado em um mapa Mapbox GL JS real, diretamente no chat
  • Imagens de mapas estáticos para criar representações visuais de locais, rotas e dados geográficos
  • Cálculos geoespaciais offline de distância, área, rumo, zonas de amortecimento e análise espacial, sem exigir chamadas de API

Seja para criar um assistente de viagens com IA, um otimizador de logística, um recomendador baseado em localização ou qualquer aplicativo que precise entender “onde”, o Mapbox MCP Server oferece a inteligência espacial necessária para tornar isso possível. Você também pode ativá-lo em clientes populares, como Claude Desktop e VS Code. Veja os detalhes abaixo.

Mapbox MCP Server Demo

Uso

É necessário um token de acesso do Mapbox 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, consulte o Guia do servidor MCP hospedado.

Para obter um token de acesso do Mapbox:

  1. Crie uma conta gratuita do Mapbox em mapbox.com/signup
  2. Acesse sua página da conta
  3. Crie um novo token ou use o token público padrão

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

Guias de integração

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

Exemplos de prompts

Após a configuração, experimente estes prompts no Claude Desktop ou em outros clientes MCP:

Contextualização de localização

Para consultas que priorizam coordenadas — “o que há perto de mim”, “que bairro é este”, “o que posso alcançar em N minutos” — use ground_location_tool. Ele combina geocodificação reversa, pesquisa por categoria e isócrona em uma única chamada, escolhendo de forma adaptativa a estratégia adequada com base na consulta e retornando registros tipados (nomes, endereços, coordenadas, distâncias, polígonos de alcance) com citações.

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

  • Bairro — “Que bairro fica em 47.6097, -122.3408 e o que há por perto?”
  • POI — “Cafeterias a até 10 minutos de caminhada 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?”
  • Rotas — “Ponto mais próximo com acesso por rota para deixar alguém em 34.0522, -118.2437”

Descoberta de locais

  • “Encontre cafeterias a uma distância que dê para percorrer a pé do Empire State Building”
  • “Quero ir de Seattle a Portland. Há algum Starbucks no caminho?”
  • “Mostre postos de gasolina ao longo da rota de Boston a Nova York”
  • “Quais restaurantes ficam perto da Times Square?”

Navegação e viagens

  • “Obtenha instruções de direção do LAX a Hollywood com o trânsito atual”
  • “Quanto tempo levaria para caminhar do Central Park à Times Square?”
  • “Calcule o tempo de viagem do meu hotel (Four Seasons) ao Aeroporto JFK de táxi durante o horário de pico”

Visualização e mapas

  • “Usando a ferramenta de renderização de mapas do Mapbox, mostre instruções de rota da Golden Gate Bridge à Union Square, em San Francisco” — renderiza uma rota interativa e ao vivo em um mapa Mapbox real
  • “Crie uma imagem de mapa mostrando a rota da Golden Gate Bridge ao Fisherman's Wharf, com marcadores nos dois locais”
  • “Mostre uma vista de satélite de Manhattan com os principais pontos de referência marcados”
  • “Gere um mapa destacando todos os locais do Starbucks a até uma milha do centro de Seattle”
  • “Mostre um polígono preenchido sobre estas coordenadas: [...], com um marcador identificado como ‘Armazém’ em [...]” — renderiza seu próprio GeoJSON diretamente por meio de render_map_tool, sem precisar de nenhuma outra ferramenta do Mapbox

Análise e planejamento

  • “Mostre as áreas alcançáveis em até 30 minutos de carro do centro de Portland”
  • “Calcule uma matriz de tempo de viagem entre estes 3 hotéis (Marriott, Sheraton e Hilton) e o centro de convenções em Denver”
  • “Encontre a rota ideal para visitar estas 3 atrações turísticas (Golden Gate, Musical Stairs e Fisherman's Wharf) em San Francisco”
  • “Otimize uma rota de entrega para estes 8 endereços: [lista de endereços]”

GPS e correspondência de rotas

  • “Limpe este trajeto de GPS e mostre a rota real nas vias: [lista de coordenadas com registros de data e hora]”
  • “Ajuste este passeio de bicicleta gravado à rede cicloviária: [coordenadas de GPS]”
  • “Associe esta rota de carro à rede viária e mostre os níveis de congestionamento”

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 fica dentro deste polígono de área de serviço?”
  • “Qual é o rumo de San Francisco a Nova York?”
  • “Encontre o ponto médio entre Londres e Paris”
  • “Crie uma zona de amortecimento de 5 milhas ao redor deste local”
  • “Calcule o centroide do limite deste bairro”
  • “Qual é a caixa delimitadora destas coordenadas de rota?”
  • “Simplifique este polígono complexo para reduzir o número de pontos”

Dicas para obter melhores resultados

  • Seja específico sobre os locais (use endereços completos ou nomes de pontos de referência)
  • Especifique seu meio de transporte preferido (carro, caminhada, bicicleta)
  • Inclua restrições de horário quando forem relevantes (“durante o horário de pico”, “às 15h”)
  • Peça formatos de saída específicos quando necessário (“como imagem de mapa”, “em formato JSON”)

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

Recursos

O servidor MCP expõe dados de referência estáticos como recursos MCP. Os recursos oferecem acesso somente leitura a dados que os clientes podem consultar diretamente, sem fazer chamadas de ferramentas.

Recursos disponíveis

Recurso de categorias do Mapbox

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

Acesse a lista completa de IDs de categorias disponíveis para usar com a ferramenta de pesquisa por categoria. As categorias podem ser usadas para filtrar resultados de pesquisa por tipo (por exemplo, “restaurant”, “hotel”, “gas_station”).

Exemplos:

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

Acessar 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 mapas detalhadas (render_map_tool)

Todas as ferramentas geoespaciais deste servidor (rotas, isócronas, pesquisa e outras) podem exibir seus resultados como um mapa Mapbox GL JS interativo e ao vivo por meio de render_map_tool — a única primitiva de visualização do servidor. Ela é renderizada pelo protocolo MCP Apps (@modelcontextprotocol/ext-apps) como um painel HTML independente, diretamente no chat, com um botão de tela cheia, nos clientes compatíveis:

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

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

Se precisar de uma imagem estática garantida em clientes sem suporte a MCP Apps, use static_map_image_tool — ela retorna um PNG/JPEG codificado em base64 que qualquer cliente pode exibir.

CLIENT_NEEDS_RESOURCE_FALLBACK

Ferramentas alternativas para recursos (opcionais para clientes não compatíveis)

Os recursos são uma funcionalidade essencial do MCP, compatível com a maioria dos clientes (Claude Desktop, VS Code, MCP Inspector etc.). No entanto, alguns clientes (como smolagents) não oferecem suporte a recursos. Para esses clientes, o servidor pode fornecer “ferramentas alternativas para recursos”, que disponibilizam o mesmo conteúdo dos recursos por meio de chamadas de ferramentas.

Ferramentas alternativas:

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

Por padrão, essas ferramentas NÃO são incluídas (pressupõe-se que seu cliente ofereça suporte a recursos). Se seu cliente não oferecer suporte a recursos, ative as ferramentas alternativas:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Quando definir esta opção:

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

Ferramentas

Ferramentas utilitárias

Ferramenta de leitura de recursos

Oferece acesso a recursos MCP para clientes que não oferecem suporte à API nativa de recursos MCP. Use esta ferramenta para ler recursos, como a lista de categorias.

Parâmetros:

  • uri: URI do recurso a ser lido (por exemplo, mapbox://categories, mapbox://categories/ja)

Exemplos de uso:

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

Observação: se seu cliente MCP oferecer suporte a recursos nativos, prefira usar diretamente a API de recursos para obter melhor desempenho.

Ferramentas geoespaciais offline

Estas ferramentas realizam cálculos geoespaciais totalmente offline, sem exigir chamadas à API do 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:

  • Suporte a várias unidades: quilômetros, milhas, metros, pés e milhas náuticas
  • Cálculo preciso da distância de grande círculo
  • Não exige chamadas à API

Exemplo de uso: “Qual é a distância entre San 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 em relação a um polígono ou multipolígono, retornando apenas os que estiverem dentro. Aceita um único ponto ou um lote em uma chamada.

Recursos:

  • Funciona com polígonos complexos, incluindo buracos
  • Oferece suporte a multipolígonos
  • Testa qualquer quantidade 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 ficam dentro da nossa área de atendimento?"

Ferramenta de destino

Calcula um ponto de destino com base em um ponto inicial, um rumo e uma distância, usando um deslocamento geodésico (de grande círculo).

Recursos:

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

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

Ferramenta de rumo

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

Recursos:

  • Retorna o rumo em graus (0-360°)
  • Fornece a direção cardeal (N, NE, E, SE, S, SW, W, NW)
  • Útil para navegação e consultas direcionais

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

Ferramenta de ponto médio

Encontra o ponto médio geográfico entre duas coordenadas ao longo da trajetória de grande círculo.

Recursos:

  • Calcula o ponto médio real na superfície curva da Terra
  • Útil para sugerir pontos de encontro
  • Lida corretamente com cálculos de longas distâncias

Exemplo de uso: "Qual é o ponto intermediário entre San Francisco e New York?"

Ferramenta de centroide

Calcula o centro geométrico (centroide) de um polígono ou multipolígono.

Recursos:

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

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

Ferramenta de área

Calcula a área de um polígono.

Recursos:

  • Oferece suporte a várias unidades: metros quadrados, quilômetros quadrados, acres, hectares, milhas quadradas e pés quadrados
  • Cálculo preciso da á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

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

Recursos:

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

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

Ferramenta de buffer

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

Recursos:

  • Oferece suporte a várias unidades de distância
  • Cria buffers circulares ao redor de pontos
  • Útil para análise de proximidade e criação de zonas de influência

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

Ferramenta de simplificação

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

Recursos:

  • Tolerância configurável para o nível de detalhe
  • Preserva a forma geral enquanto reduz a complexidade
  • Útil para reduzir o tamanho dos arquivos e melhorar o desempenho da renderização
  • Opção para manter a topologia (evitar autointerseções)

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

Ferramenta de comprimento

Mede o comprimento total de uma linha definida por uma série de coordenadas.

Recursos:

  • Oferece suporte a quilômetros, milhas, metros e pés
  • Útil para medir uma rota, caminho ou limite desenhado sem uma chamada à API de roteamento

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

Ferramenta convexa

Calcula o fecho convexo de um conjunto de pontos — o menor polígono convexo que contém todos eles.

Recursos:

  • Ú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 todos estes locais de lojas?"

Ferramenta de ponto mais próximo

Encontra o ponto mais próximo de uma coleção em relação a um ponto de destino.

Recursos:

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

Exemplo de uso: "Qual destas lojas fica mais perto da minha localização atual?"

Ferramenta de ponto mais próximo em uma linha

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

Recursos:

  • Útil para perguntas como "qual ponto desta rota fica mais perto da minha localização?" ou para fazer correspondência com o mapa sem uma chamada à API

Exemplo de uso: "Em que ponto desta trilha estou mais perto agora?"

Ferramentas de união, interseção e diferença

Combina ou compara dois ou mais polígonos — union_tool os mescla em uma geometria, intersect_tool encontra a área compartilhada entre eles e difference_tool subtrai um do outro.

Recursos:

  • Útil para combinar áreas de atendimento, encontrar sobreposições de cobertura ou calcular zonas de exclusão (por exemplo, "o que está coberto pela zona A, mas não pela zona B?")
  • Funciona totalmente offline — não requer chamadas de API
  • Cada ferramenta 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?" / "Que parte desta área de atendimento não está coberta pela nossa isócrona de 15 minutos?"

Ferramentas da API Mapbox

Ferramenta de lista de categorias (obsoleta)

⚠️ Obsoleta: Use resource_reader_tool com o URI mapbox://categories ou acesse diretamente o recurso mapbox://categories se o seu cliente oferecer suporte a recursos MCP.

Esta ferramenta é mantida para compatibilidade com versões anteriores de clientes que não oferecem suporte a recursos MCP ou a resource_reader_tool.

Ferramenta de matriz

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

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

Ferramenta de imagem estática

Gera imagens estáticas de mapas usando a API Static Images do Mapbox. Os recursos incluem:

  • Estilos de mapa personalizados (ruas, áreas externas, satélite etc.)
  • Dimensões de imagem e níveis de zoom ajustáveis
  • Suporte a vários marcadores com cores e rótulos personalizados
  • Opções de sobreposição, incluindo polilinhas e polígonos
  • Ajuste automático às coordenadas especificadas

Ferramenta de busca por categoria

Realiza uma busca por categoria usando a API de busca por categoria do Search Box do Mapbox. Os recursos incluem:

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

Ferramenta de geocodificação reversa

Realiza geocodificação reversa usando a API Geocoding V6 do Mapbox. Os recursos incluem:

  • Conversão de coordenadas geográficas em endereços legíveis
  • Níveis de detalhe personalizáveis (rua, bairro, cidade etc.)
  • Filtragem de resultados por tipo (endereço, ponto de interesse, bairro etc.)
  • Suporte a vários idiomas
  • Informações detalhadas sobre o contexto do local

Ferramenta de localização no terreno

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

Recursos:

  • Classifica a consulta (roteamento, contexto do bairro, busca de pontos de interesse ou região/alcance) e busca apenas os dados relevantes
  • Busca de pontos de interesse próximos por categoria, quando solicitada
  • Resumo do alcance por tempo de viagem (com base em isócronas)
  • Retorna uma referência render_map_tool com a localização fundamentada e os pontos de interesse próximos plotados

Exemplo de uso: "Em que bairro fica esta coordenada e há cafeterias por perto?"

Ferramenta de detalhes do local

Recupera informações detalhadas sobre um local específico usando seu ID do Mapbox — fotos, horário 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: "Conte-me mais sobre o primeiro resultado de cafeteria — horário de funcionamento, número de telefone e site"

Ferramenta de direções

Busca direções de rota usando a API Directions do Mapbox. Os recursos incluem:

  • Suporte a diferentes perfis de roteamento: direção (com trânsito em tempo real ou típico), caminhada e ciclismo
  • Rotas com vários pontos de passagem (2-25 pares de coordenadas)
  • Opção de rotas alternativas
  • Anotações da rota (distância, duração, velocidade, congestionamento)
  • Opções de agendamento:
    • Horário de partida futuro (depart_at) para os perfis driving e driving-traffic
    • Horário de chegada desejado (arrive_by) apenas para o perfil driving
  • Otimizações específicas por perfil:
    • Direção: restrições de dimensões do veículo (altura, largura, peso)
  • Opções de exclusão para o roteamento:
    • Exclusões comuns: rotas de balsa, pedágios pagos apenas em dinheiro
    • Exclusões específicas para direção: pedágios, rodovias, estradas não pavimentadas, túneis, fronteiras entre países e fronteiras estaduais
    • Exclusões de pontos personalizados (até 50 pontos geográficos a evitar)
  • Formato de saída da geometria GeoJSON

Ferramenta de isócrona

Calcula áreas alcançáveis em um período especificado a partir de um local usando a API Isochrone do Mapbox. Os recursos incluem:

  • Suporte a diferentes perfis de viagem (direção, caminhada, ciclismo)
  • Tempos ou distâncias de viagem personalizáveis
  • Geração de vários contornos (por exemplo, intervalos de 15, 30 e 45 minutos)
  • Especificação opcional do horário de partida ou chegada
  • Personalização de cores para visualização

Ferramenta de busca e geocodificação

Usa o endpoint da API Text Search do Search Box do Mapbox para realizar buscas e geocodificar pontos de interesse, endereços, locais e outros tipos compatíveis com essa API. Esta ferramenta reúne em uma única ferramenta as funcionalidades anteriormente fornecidas por ForwardGeocodeTool e PoiSearchTool (em versões anteriores deste servidor MCP).

Ferramenta de correspondência com o mapa

Ajusta trajetos de GPS à rede viária usando a API Map Matching do Mapbox. Os recursos incluem:

  • Conversão de trajetos de GPS imprecisos em rotas precisas na rede viária
  • Suporte a diferentes perfis de viagem (driving, driving-traffic, walking, cycling)
  • Até 100 pares de coordenadas por solicitação
  • Carimbos de data e hora opcionais para melhorar a precisão com base na velocidade
  • Raios de ajuste configuráveis para diferentes níveis de qualidade do GPS
  • Anotações da rota (limites de velocidade, distância, duração, congestionamento)
  • Vários formatos de saída da geometria (GeoJSON, polyline)

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

Ferramenta de otimização

Encontra a rota ideal entre vários locais usando a API Optimization do Mapbox. Os recursos incluem:

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

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

Observação: Está disponível uma API V2 com recursos avançados (janelas de tempo, restrições de capacidade, vários veículos), mas é necessário ter acesso beta. A implementação da V2 está incluída na base de código, mas não é registrada por padrão.

Ferramenta de feedback

Envia o feedback de um usuário sobre o aplicativo ou agente ao desenvolvedor por meio da API Feedback do Mapbox (prévia pública). O feedback é registrado na conta proprietária do token de acesso. Assim, quando você cria um aplicativo ou agente neste servidor usando seu próprio token, o feedback dos usuários aparece no mesmo feed dos relatórios do Feedback Agent dos seus aplicativos, e você pode analisá-lo no Feedback Explorer. Ele não comunica problemas ao Mapbox. Assim como o Feedback Agent, serve para registrar qualquer comentário sobre seu produto que ajude você a entender as necessidades dos usuários, por exemplo:

  • Um lugar que fechou, tem informações incorretas ou está no local errado
  • Um lugar ou endereço que não pode ser encontrado
  • Uma via fechada, um limite de velocidade incorreto ou informações de trânsito incorretas
  • Uma rota com uma conversão ou entrada ilegal, ou sem rota alguma
  • Algo sobre o próprio app, como um bug ou uma sugestão (application_issue)

Ele envia o texto do feedback, uma categoria e a localização, e retorna o ID e o status do item. A localização é opcional para feedback que não seja sobre um lugar; a API exige uma, então a ferramenta envia 0, 0, conforme recomendado pela equipe da Feedback API por enquanto. Nada é enviado sem a autorização do usuário: clientes compatíveis com elicitação exibem primeiro uma solicitação de confirmação, e a descrição da ferramenta pede que o modelo confirme no chat em todos os outros casos.

A Feedback API é gratuita durante a Public Preview. Na General Availability, o Feedback Agent cobra US$ 0,02 por item de feedback. Para evitar registrar o mesmo problema duas vezes, antes de enviar, a ferramenta verifica os relatórios da própria conta dos últimos 30 dias. Se houver um relatório da mesma categoria, a até 50 m, ainda aguardando análise (feedback sem localização não é verificado), ela retorna esse relatório em vez de enviar um novo. A Feedback API lista apenas os relatórios da própria conta, então não é possível detectar relatórios de outras contas. send_anyway: true ignora a verificação quando o usuário diz que o problema é diferente.

Requisitos: o token de acesso precisa do escopo user-feedback:write para enviar e de user-feedback:read para verificar duplicatas. Sem o escopo de gravação, a ferramenta retorna um erro informando isso. Sem o escopo de leitura, ela envia sem verificar e informa isso no resultado. Para omitir a ferramenta, inicie o servidor com --disable-tools feedback_tool.

Exemplo de uso: "A Blue Bottle na Mint St fechou no ano passado. Você pode enviar isso como feedback?"

Ferramenta Report

Envia feedback sobre o próprio servidor Mapbox MCP à equipe da Mapbox que o desenvolve: um bug, uma ferramenta que retornou um resultado incorreto ou confuso, um recurso ausente ou uma sugestão. O feedback é registrado na própria conta da Mapbox, não na sua, portanto não precisa de um escopo de token adicional e não pode ser consultado nem retirado depois. Não serve para relatar dados incorretos de mapas, lugares ou rotas.

O servidor acrescenta ao final do texto a versão dele, o nome e a versão do cliente e a ferramenta à qual o feedback se refere. Nada é enviado sem a autorização do usuário: clientes compatíveis com elicitação exibem primeiro uma solicitação de confirmação, e a descrição da ferramenta pede que o modelo confirme no chat em todos os outros casos.

Ela usa o endpoint que a equipe da Feedback API adicionou para o comando mapbox report da Mapbox CLI. Para omitir a ferramenta, inicie o servidor com --disable-tools report_tool.

Exemplo de uso: "O mapa não desenhou nenhuma das minhas isócronas. Você pode avisar a equipe do Mapbox MCP?"

Ferramenta List public tokens

Lista os tokens de acesso públicos (pk.) da conta, para um agente que esteja criando uma página da web ou um app fora do chat que carregue o Mapbox GL JS ou chame as APIs da Mapbox pelo navegador. No chat, render_map_tool não precisa de token. Cada token inclui o nome, se é o padrão, as restrições de URL e os escopos.

Informe site_url (onde a página será executada), e a ferramenta recomenda um token restrito a essa URL, caso a conta tenha um. Caso contrário, recomenda o token público padrão e informa que um site publicado deve usar um token restrito por URL, com um link para criar um. Qualquer pessoa que copie um token público sem restrições pode usá-lo, e o uso será cobrado na conta.

Ela nunca retorna tokens secretos ou temporários e não pode criar tokens (isso requer tokens:write; o create_token_tool do servidor DevKit faz isso).

Requisitos: para listar, é necessário o escopo tokens:read, o mesmo que o mapa no chat já usa para encontrar o token público padrão. Com um token de acesso pk., ou quando a listagem falha no próprio MAPBOX_ACCESS_TOKEN do servidor e MAPBOX_PUBLIC_TOKEN está definido, ela retorna esse token. Um chamador com seu próprio token bearer (o servidor hospedado) nunca recebe MAPBOX_PUBLIC_TOKEN, e um token restrito a outras URLs nunca é recomendado. Para omitir a ferramenta, inicie o servidor com --disable-tools list_public_tokens_tool.

Exemplo de uso: "Crie um site de página única que mostre os três endereços das nossas lojas em um mapa da Mapbox."

Desenvolvimento

Inspecionar 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 uma nova ferramenta

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

Lançar 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 publisher valida se as versões de package.json e server.json correspondem à versão do lançamento. Ignorar a atualização da versão ou a sincronização do manifesto causará falhas na publicação.

Rastreamento com OpenTelemetry

Este servidor MCP inclui rastreamento abrangente com 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

Observação: o servidor carrega automaticamente a configuração do arquivo .env na inicialização. O arquivo .env.example inclui exemplos de configuração para várias plataformas de observabilidade.

Plataformas de observabilidade compatíveis

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
  • 📊 Qualquer backend compatível com OTLP

Configuração para produção

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

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

Recursos de rastreamento:

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

Contribuições

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

Padrões e diretrizes completos:

Início rápido para colaboradores

  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 programação
  4. Execute os testes e o lint: npm test && npm run lint
  5. Adicione testes para qualquer funcionalidade nova
  6. Envie um pull request com uma descrição clara

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

Uso de dados e privacidade

Quais dados são enviados às APIs da Mapbox

Quando você usa as ferramentas do servidor MCP, os seguintes dados são enviados diretamente do seu ambiente às APIs da Mapbox:

  • Ferramentas de geocodificação: texto de endereço/localização, coordenadas, filtros de país/região
  • Ferramentas de busca: consultas de busca, coordenadas de localização para proximidade, filtros de categoria
  • Ferramenta de rotas: coordenadas de início/fim, pontos de passagem, preferências de rota, restrições do veículo
  • Ferramenta de matriz: vários 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ócronas: 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 às APIs da Mapbox
  • Segurança do token: seu token de API da Mapbox permanece na sua máquina local e nunca é transmitido a este servidor MCP nem armazenado por ele
  • Sem armazenamento de dados: este servidor MCP não armazena, registra nem coleta seus dados ou solicitações de API
  • Comunicação direta: não há servidor intermediário entre você e as APIs da Mapbox

Uso de dados por terceiros

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

Suporte e contato

Para problemas com o servidor MCP

Para dúvidas sobre as APIs da Mapbox

Compromisso de manutenção

Este servidor MCP é mantido oficialmente pela Mapbox, Inc. Oferecemos:

  • Atualizações regulares para novos recursos das APIs da Mapbox
  • Correções de bugs e atualizações de segurança
  • Compatibilidade com as versões mais recentes do protocolo MCP
  • Suporte à comunidade por meio dos problemas no GitHub

Licença MIT