google-maps-mcp-server

Servidor MCP baseado em STDIO para as APIs da Plataforma Google Maps

Documentação

Servidor MCP do Google Maps

Um servidor Model Context Protocol (MCP) que fornece acesso abrangente às APIs da plataforma Google Maps. Este servidor permite que LLMs realizem geocodificação, busca de lugares, roteamento e outras operações geoespaciais por meio de uma interface padronizada.

Recursos

🗺️ Integração abrangente com o Google Maps - Acesso às APIs de Places, Routes, Geocoding e utilitários
🔍 Busca avançada de lugares - Busca por texto, busca por proximidade, autocompletar e informações detalhadas de lugares
🛣️ Roteamento inteligente - Cálculo de rotas com tráfego em tempo real, pedágios e rotas alternativas
📍 Geocodificação precisa - Geocodificação direta e reversa com suporte internacional
🌐 Serviços de geolocalização - Estimativa de localização por IP e WiFi/celular
📊 Recursos ricos - Documentação e exemplos integrados acessíveis via recursos MCP
🔒 Segurança em primeiro lugar - Validação de entrada, limitação de taxa e tratamento seguro de chaves de API

Início Rápido

1. Obtenha a Chave da API do Google Maps

Acesse o Google Cloud Console
Crie um novo projeto ou selecione um existente
Ative as APIs necessárias (veja os requisitos de API por ferramenta abaixo)
Crie uma chave de API e restrinja-a às APIs ativadas
Importante: Este servidor usa as novas APIs da plataforma Google Maps (Places API (Nova) e Routes API), não as versões legadas

Requisitos de API por Ferramenta

Ferramenta	API necessária no Google Cloud Console
`geocode_search`, `geocode_reverse`	Geocoding API
`places_search_text`, `places_nearby`, `places_autocomplete`, `places_details`, `places_photos`	Places API (Nova)
`routes_compute`, `routes_matrix`	Routes API
`elevation_get`	Elevation API
`timezone_get`	Time Zone API
`geolocation_estimate`	Geolocation API
`roads_nearest`	Roads API
`ip_geolocate`, `nearby_find`	Geolocation API + Places API (Nova)

2. Configure o Cliente MCP

Adicione o servidor à configuração do seu cliente MCP:

Cursor

Adicione às configurações MCP do Cursor (~/.cursor/mcp.json ou pelo Command Palette > Open MCP Settings > New MCP Server):

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Com limitação de taxa personalizada:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here",
        "GOOGLE_MAPS_RATE_LIMIT_ENABLED": "true",
        "GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS": "120000",
        "GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS": "200"
      }
    }
  }
}

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Com limitação de taxa desativada:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here",
        "GOOGLE_MAPS_RATE_LIMIT_ENABLED": "false"
      }
    }
  }
}

Outros Clientes MCP

# Set environment variable
export GOOGLE_MAPS_API_KEY="your-api-key-here"

# Run the server
npx google-maps-mcp-server

Ferramentas Disponíveis

Geocodificação

geocode_search - Converte endereços em coordenadas
geocode_reverse - Converte coordenadas em endereços

Lugares

places_search_text - Busca lugares com linguagem natural
places_nearby - Encontra lugares dentro de um raio
places_autocomplete - Obtém sugestões de lugares
places_details - Obtém informações detalhadas de lugares
places_photos - Obtém URLs de fotos de lugares

Roteamento

routes_compute - Calcula rotas ideais
routes_matrix - Calcula matrizes de distância

Utilitários

elevation_get - Obtém dados de elevação
timezone_get - Obtém informações de fuso horário
geolocation_estimate - Estima localização a partir de dados WiFi/celular
roads_nearest - Encontra as estradas mais próximas

Ferramentas Especiais

nearby_find - Encontra cidades, vilas ou POIs próximos
ip_geolocate - Geolocaliza usando endereço IP

Exemplos de Uso

Encontrar Restaurantes Próximos

{
  "tool": "places_nearby",
  "arguments": {
    "location": {"lat": 37.7749, "lng": -122.4194},
    "radius_meters": 1000,
    "included_types": ["restaurant"],
    "max_results": 10
  }
}

Obter Direções de Direção

{
  "tool": "routes_compute",
  "arguments": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Los Angeles, CA"},
    "travel_mode": "DRIVE",
    "routing_preference": "TRAFFIC_AWARE"
  }
}

Geocodificar um Endereço

{
  "tool": "geocode_search",
  "arguments": {
    "query": "1600 Amphitheatre Parkway, Mountain View, CA",
    "language": "en"
  }
}

Geolocalizar por Endereço IP

{
  "tool": "ip_geolocate",
  "arguments": {
    "reverse_geocode": true
  }
}

A ferramenta ip_geolocate também suporta um parâmetro opcional ip_override para testar com diferentes endereços IP:

{
  "tool": "ip_geolocate",
  "arguments": {
    "ip_override": "8.8.8.8",
    "reverse_geocode": true
  }
}

Observação: O parâmetro ip_override aceita endereços IPv4 ou IPv6 públicos. Faixas de IP privadas e reservadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8) são rejeitadas. A substituição de IP é de melhor esforço e a API de Geolocalização do Google pode nem sempre atender à solicitação.

Configuração

Variáveis de Ambiente

GOOGLE_MAPS_API_KEY (obrigatório) - Sua chave da API da plataforma Google Maps

Configuração de Limitação de Taxa

GOOGLE_MAPS_RATE_LIMIT_ENABLED (opcional, padrão: true) - Ativa/desativa a limitação de taxa
- Defina como false para desativar completamente a limitação de taxa
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS (opcional, padrão: 60000) - Janela de limitação de taxa em milissegundos
- Controla a janela de tempo para limitação de taxa (ex.: 60000 = 1 minuto)
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS (opcional, padrão: 100) - Máximo de solicitações por janela
- Número máximo de solicitações permitidas por endpoint dentro da janela de tempo

Exemplos de Configurações de Limitação de Taxa

# Default rate limiting (100 requests per minute per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"

# Disable rate limiting entirely
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_ENABLED=false

# Custom rate limiting (200 requests per 2 minutes per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS=120000
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS=200

# Stricter rate limiting (50 requests per 30 seconds per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS=30000
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS=50

Cotas de API e Cobrança

Este servidor usa APIs da plataforma Google Maps que exigem cobrança ativada. Monitore seu uso no Google Cloud Console para evitar cobranças inesperadas. Considere implementar limites de uso em sua aplicação.

Recursos

O servidor fornece recursos MCP integrados com documentação e exemplos:

google-maps://docs/api-overview - Visão geral da API e capacidades
google-maps://docs/place-types - Referência completa de tipos de lugares
google-maps://docs/travel-modes - Modos de viagem disponíveis
google-maps://docs/field-masks - Otimização de campos da Places API
google-maps://examples/common-queries - Consultas e padrões de exemplo

Acesse-os pela interface de recursos do seu cliente MCP.

Desenvolvimento

Compilando a partir do Código Fonte

git clone <repository-url>
cd google-maps-mcp-server
npm install
npm run build

Testes

npm test

Usando o MCP Inspector

npm run build

GOOGLE_MAPS_API_KEY="your-api-key-here" npx @modelcontextprotocol/inspector ./dist/index.js

Tratamento de Erros

O servidor retorna erros estruturados com contexto útil:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "API quota exceeded",
    "context": {
      "endpoint": "/places/textsearch",
      "status": 429
    }
  }
}

Códigos de erro comuns:

INVALID_REQUEST - Parâmetros de entrada inválidos
API_KEY_INVALID - Chave de API inválida ou ausente
QUOTA_EXCEEDED - Cota da API excedida
REQUEST_FAILED - Falha de rede ou solicitação de API

Segurança

Chaves de API nunca são registradas ou expostas
Validação de entrada previne ataques de injeção
Limitação de taxa protege contra abuso
Endereços IP são criptografados nos registros para privacidade

Contribuições

Contribuições são bem-vindas! Envie pull requests para nosso repositório no GitHub.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.