MCP Google Map Server

Integra a API do Google Maps para consultas baseadas em localização e processamento de dados.

GitHub

447

Experimente este MCPPatrocinado

Documentação

Dê ao seu agente de IA a capacidade de entender o mundo físico —
geocodificar, traçar rotas, pesquisar e raciocinar sobre locais.

English | 繁體中文

Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget

18 ferramentas — 14 atômicas + 4 compostas (explore-area, plan-route, compare-places, local-rank-tracker)
3 modos — stdio, StreamableHTTP, CLI de execução standalone
Agent Skill — definição de skill integrada ensina a IA a encadear ferramentas geo (skills/google-maps/)

vs Google Grounding Lite

	Este projeto	Grounding Lite
Ferramentas	18	3
Geocodificação	Sim	Não
Direções passo a passo	Sim	Não
Elevação	Sim	Não
Matriz de distâncias	Sim	Não
Detalhes do lugar	Sim	Não
Fuso horário	Sim	Não
Clima	Sim	Sim
Qualidade do ar	Sim	Não
Imagens de mapa	Sim	Não
Ferramentas compostas (explorar, planejar, comparar)	Sim	Não
Código aberto	MIT	Não
Auto-hospedado	Sim	Somente gerenciado pelo Google
Agent Skill	Sim	Não

Início Rápido

# stdio (Claude Desktop, Cursor, etc.)
npx @cablate/mcp-google-map --stdio

# exec CLI — no server needed
npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'

# HTTP server
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

Agradecimentos Especiais

Agradecimento especial a @junyinnnn por ajudar a adicionar suporte para streamablehttp.

Ferramentas Disponíveis

Ferramenta	Descrição
`maps_search_nearby`	Encontre lugares próximos a um local por tipo (restaurante, café, hotel, etc.). Suporta filtros por raio, avaliação e status de funcionamento.
`maps_search_places`	Busca de lugares por texto livre (ex.: "restaurantes de sushi em Tóquio"). Suporta viés de localização, avaliação e filtros de abertos agora.
`maps_place_details`	Obtenha detalhes completos de um lugar pelo place_id — avaliações, telefone, site, horários. O parâmetro opcional `maxPhotos` retorna URLs de fotos.
`maps_geocode`	Converta um endereço ou nome de ponto de referência em coordenadas GPS.
`maps_reverse_geocode`	Converta coordenadas GPS em um endereço.
`maps_distance_matrix`	Calcule distâncias e tempos de viagem entre múltiplas origens e destinos. O modo de direção suporta `avoid_tolls` e `avoid_highways`.
`maps_directions`	Obtenha navegação passo a passo entre dois pontos com detalhes da rota. O modo de direção suporta `avoid_tolls` e `avoid_highways`.
`maps_elevation`	Obtenha elevação (metros acima do nível do mar) para coordenadas geográficas.
`maps_timezone`	Obtenha ID de fuso horário, nome, offsets UTC/DST e hora local para coordenadas.
`maps_weather`	Obtenha condições climáticas atuais ou previsão — temperatura, umidade, vento, UV, precipitação.
`maps_air_quality`	Obtenha índice de qualidade do ar, concentrações de poluentes e recomendações de saúde por grupo demográfico.
`maps_static_map`	Gere uma imagem de mapa com marcadores, caminhos ou rotas — retornada inline para o usuário ver diretamente.
`maps_batch_geocode`	Geocodifique até 50 endereços em uma única chamada — retorna coordenadas para cada um.
`maps_search_along_route`	Pesquise lugares ao longo de uma rota entre dois pontos — classificados por tempo mínimo de desvio.
Ferramentas Compostas
`maps_explore_area`	Explore o que há ao redor de um local — pesquisa vários tipos de lugar e obtém detalhes em uma única chamada.
`maps_plan_route`	Planeje uma rota otimizada com múltiplas paradas — usa otimização de waypoints da Routes API (até 25 paradas) para ordenação eficiente. O modo de direção suporta `avoid_tolls` e `avoid_highways`.
`maps_compare_places`	Compare lugares lado a lado — pesquisa, obtém detalhes e opcionalmente calcula distâncias.
`maps_local_rank_tracker`	Acompanhe o ranking de busca local de um negócio em uma grade geográfica — como o LocalFalcon. Suporta até 3 palavras-chave para varredura em lote. Retorna a posição em cada ponto, os 3 principais concorrentes e métricas (ARP, ATRP, SoLV).

Todas as ferramentas são anotadas com readOnlyHint: true e destructiveHint: false — clientes MCP podem aprovar automaticamente sem confirmação do usuário.

Pré-requisito: Ative a Places API (New) e a Routes API no Google Cloud Console antes de usar ferramentas relacionadas a lugares e rotas.

Instalação

Método 1: stdio (Recomendado para a maioria dos clientes)

Funciona com Claude Desktop, Cursor, VS Code e qualquer cliente MCP que suporte stdio:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Reduza o uso de contexto — Se você precisar apenas de um subconjunto de ferramentas, defina GOOGLE_MAPS_ENABLED_TOOLS para limitar quais ferramentas são registradas:

{
  "env": {
    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
  }
}

Omita ou defina como * para todas as 18 ferramentas (padrão).

Método 2: Servidor HTTP

Para implantações multi-sessão, isolamento de chave de API por requisição ou acesso remoto:

npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

# Bind to all interfaces for remote access (e.g. Docker, LAN)
npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"

Em seguida, configure seu cliente MCP:

{
  "mcpServers": {
    "google-maps": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Informações do Servidor

Transporte: stdio (--stdio) ou Streamable HTTP (padrão)
Ferramentas: 18 ferramentas do Google Maps (14 atômicas + 4 compostas) — filtráveis via GOOGLE_MAPS_ENABLED_TOOLS

Modo de Execução CLI (Agent Skill)

Use as ferramentas diretamente sem executar o servidor MCP:

npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'

Todas as 18 ferramentas disponíveis: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather, air-quality, static-map, batch-geocode-tool, search-along-route, explore-area, plan-route, compare-places, local-rank-tracker. Consulte skills/google-maps/ para a definição da skill do agente e documentação completa de parâmetros.

Geocodificação em Lote

Geocodifique centenas de endereços a partir de um arquivo:

npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -

Entrada: um endereço por linha. Saída: JSON com { total, succeeded, failed, results[] }. Concorrência padrão: 20 requisições paralelas.

Configuração da Chave de API

As chaves de API podem ser fornecidas de três maneiras (ordem de prioridade):

Cabeçalhos HTTP (Maior prioridade)

{
  "mcp-google-map": {
    "transport": "streamableHttp",
    "url": "http://localhost:3000/mcp",
    "headers": {
      "X-Google-Maps-API-Key": "YOUR_API_KEY"
    }
  }
}

Linha de comando
```
mcp-google-map --apikey YOUR_API_KEY
```

Variável de ambiente (arquivo .env ou linha de comando)

GOOGLE_MAPS_API_KEY=your_api_key_here
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

Desenvolvimento

Desenvolvimento Local

# Clone the repository
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API key

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode
npm run dev

Testes

# Run smoke tests (no API key required for basic tests)
npm test

# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)
npm run test:e2e

Estrutura do Projeto

src/
├── cli.ts                        # CLI entry point
├── config.ts                     # Tool registration and server config
├── index.ts                      # Package exports
├── core/
│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport
├── services/
│   ├── NewPlacesService.ts       # Google Places API (New) client
│   ├── PlacesSearcher.ts         # Service facade layer
│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)
│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)
├── tools/
│   └── maps/
│       ├── searchNearby.ts       # maps_search_nearby tool
│       ├── searchPlaces.ts       # maps_search_places tool
│       ├── placeDetails.ts       # maps_place_details tool
│       ├── geocode.ts            # maps_geocode tool
│       ├── reverseGeocode.ts     # maps_reverse_geocode tool
│       ├── distanceMatrix.ts     # maps_distance_matrix tool
│       ├── directions.ts         # maps_directions tool
│       ├── elevation.ts          # maps_elevation tool
│       ├── timezone.ts           # maps_timezone tool
│       ├── weather.ts            # maps_weather tool
│       ├── airQuality.ts         # maps_air_quality tool
│       ├── staticMap.ts          # maps_static_map tool
│       ├── batchGeocode.ts       # maps_batch_geocode tool
│       ├── searchAlongRoute.ts   # maps_search_along_route tool
│       ├── exploreArea.ts        # maps_explore_area (composite)
│       ├── planRoute.ts          # maps_plan_route (composite)
│       ├── comparePlaces.ts      # maps_compare_places (composite)
│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)
└── utils/
    ├── apiKeyManager.ts          # API key management
    └── requestContext.ts         # Per-request context (API key isolation)
tests/
└── smoke.test.ts                 # Smoke + E2E test suite
skills/
├── google-maps/                  # Agent Skill — how to USE the tools
│   ├── SKILL.md                  # Tool map, recipes, invocation
│   └── references/
│       ├── tools-api.md          # Tool parameters + scenario recipes
│       ├── travel-planning.md    # Travel planning methodology
│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN
    ├── SKILL.md                  # Architecture overview + onboarding
    └── references/
        ├── architecture.md       # System design, code map, 9-file checklist
        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas
        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context
        └── decisions.md          # 10 ADRs (design decisions + rationale)

Stack de Tecnologias

TypeScript — Desenvolvimento com segurança de tipos
Node.js — Ambiente de execução
@googlemaps/places — Google Places API (New) para busca e detalhes de lugares
Google Routes API — Direções, matriz de distâncias e otimização de waypoints via REST
@googlemaps/google-maps-services-js — Geocodificação, fuso horário, elevação
@modelcontextprotocol/sdk — Implementação do protocolo MCP (v1.27+)
Express.js — Framework de servidor HTTP
Zod — Validação de esquemas

Segurança

As chaves de API são tratadas no lado do servidor
Isolamento de chave de API por sessão para implantações multi-tenant
Proteção contra DNS rebinding disponível para produção
Validação de entrada usando esquemas Zod

Para revisões de segurança empresarial, consulte Esclarecimentos de Avaliação de Segurança — uma lista de verificação de 23 itens cobrindo licenciamento, proteção de dados, gerenciamento de credenciais, contaminação de ferramentas e verificação do ambiente de execução do agente de IA.

Para relatar uma vulnerabilidade, consulte SECURITY.md.

Roadmap

Adições Recentes

Ferramenta / Recurso	O que desbloqueia	Status
`maps_static_map`	Imagens de mapa com pinos/rotas — IA multimodal pode "ver" o mapa	Concluído
`maps_air_quality`	AQI, poluentes — viagens conscientes da saúde, planejamento ao ar livre	Concluído
`maps_batch_geocode`	Geocodifique até 50 endereços em uma chamada — enriquecimento de dados	Concluído
`maps_search_along_route`	Encontre lugares ao longo de uma rota classificados por tempo de desvio — planejamento de viagem	Concluído
`maps_explore_area`	Visão geral do bairro em uma chamada (composta)	Concluído
`maps_plan_route`	Roteiro otimizado com múltiplas paradas (composta)	Concluído
`maps_compare_places`	Comparação lado a lado de lugares (composta)	Concluído
`maps_local_rank_tracker`	Acompanhamento de ranking em grade geográfica — análise de SEO local (composta)	Concluído
`GOOGLE_MAPS_ENABLED_TOOLS`	Filtrar ferramentas para reduzir o uso de contexto	Concluído

Planejado

Recurso	O que desbloqueia	Status
`maps_place_photo`	Fotos de lugares para IA multimodal — "ver" o ambiente do restaurante	Planejado
Parâmetro de idioma	Respostas em vários idiomas (ISO 639-1) em todas as ferramentas	Planejado
Modelos de Prompt MCP	Comandos de barra `/travel-planner`, `/neighborhood-scout` no Claude Desktop	Planejado
Benchmark de Raciocínio Geo	Suíte de testes com 10 cenários medindo a precisão do raciocínio geoespacial de LLMs	Pesquisa

Casos de Uso que Estamos Construindo

Estes são os cenários do mundo real que orientam nossas decisões de ferramentas:

Planejamento de viagem — "Planeje um passeio de um dia em Tóquio" (geocode → search → directions → weather)
Análise imobiliária — "Analise este bairro: escolas, deslocamento, risco de enchente" (search-nearby × N + elevation + distance-matrix)
Otimização logística — "Roteie estas 12 entregas com eficiência a partir do armazém" (plan-route)
Vendas de campo — "Visite 6 clientes em Chicago, minimize o tempo de direção, encontre lugares para almoço" (plan-route + search-nearby)
Resposta a desastres — "Hospitais abertos mais próximos? Estou em uma zona de enchente?" (search-nearby + elevation)
Criação de conteúdo — "Top 5 bairros em Austin com densidade de restaurantes e distância do aeroporto" (explore-area + distance-matrix)
Acessibilidade — "Restaurantes acessíveis para cadeirantes, evite rotas íngremes" (search-nearby + place-details + elevation)
SEO local — "Audite o ranking do meu restaurante vs concorrentes em 1km" (search-places + compare-places + explore-area)

Changelog

Consulte CHANGELOG.md para o histórico de versões.

Licença

MIT

Contribuição

A participação e as contribuições da comunidade são bem-vindas! Leia CONTRIBUTING.md para configuração de desenvolvimento, diretrizes de código e o processo de pull request.

Envie Issues: Relate bugs ou forneça sugestões
Crie Pull Requests: Envie melhorias de código
Documentação: Ajude a melhorar a documentação

Contato

Email: reahtuoo310109@gmail.com
GitHub: CabLate