Google Maps

Servidor MCP do Google Maps para Cloud Run

Um servidor do Model Context Protocol (MCP) do Google Maps projetado para implantação no Google Cloud Run com acesso público. Este servidor fornece funcionalidades do Google Maps para clientes do Claude Desktop por meio de uma API segura e com limite de taxa.

Recursos

• Cálculo de Rotas: Rotas de condução ideais com dados de tráfego em tempo real
• Comparação de Rotas: Compare múltiplas alternativas de rota com diferentes opções
• Tráfego ao Vivo: Condições atuais de tráfego e análise de tempo de viagem
• Estimativa de Custos: Cálculos de custo de viagem incluindo estimativas de combustível e pedágios
• Acesso Público: Nenhuma autenticação necessária para compartilhamento fácil
• Limite de Taxa: 50 solicitações por hora por endereço IP
• Otimizado para Cloud Run: Projetado para implantação serverless no GCP

Pré-requisitos

• Conta do Google Cloud Platform com cobrança ativada
• Google Cloud CLI (gcloud) instalado e configurado
• Node.js 18+ para desenvolvimento local
• Chave da API do Google Maps com as APIs necessárias ativadas

APIs do Google Maps Necessárias

Antes da implantação, ative estas APIs no seu projeto GCP:

1. Directions API - Para cálculos de rota
2. Geocoding API - Para resolução de endereços
3. Maps JavaScript API - Para codificação de polilinhas (opcional)

Ative as APIs via Google Cloud Console ou CLI:

gcloud services enable directions-backend.googleapis.com
gcloud services enable geocoding-backend.googleapis.com
gcloud services enable maps-backend.googleapis.com

Início Rápido

1. Obtenha a Chave da API do Google Maps

1. Acesse Google Cloud Console > Credenciais
2. Crie uma nova chave de API ou use uma existente
3. Restrinja a chave às APIs necessárias listadas acima
4. Anote sua chave de API para a implantação

2. Implante no Cloud Run

# Clone the repository
git clone <your-repo-url>
cd google-maps-mcp-cloudrun

# Set your Google Maps API key
export GOOGLE_MAPS_API_KEY="your-api-key-here"

# Deploy using the provided script
./simple-deploy.sh your-gcp-project-id us-central1

3. Extraia a URL do Serviço

Após a implantação, extraia a URL do seu serviço:

# Get the service URL
SERVICE_URL=$(gcloud run services describe google-maps-mcp \
  --region us-central1 \
  --format="value(status.url)")

echo "Your MCP Server URL: $SERVICE_URL/sse"

Implantação Manual

Se você preferir implantação manual:

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Enable required services
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Deploy
gcloud run deploy google-maps-mcp \
  --source . \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_MAPS_API_KEY="your-api-key-here" \
  --memory 1Gi \
  --cpu 1 \
  --max-instances 10 \
  --timeout 300 \
  --port 8080

Configuração do Claude Desktop

Adicione esta configuração às configurações do seu Claude Desktop:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SERVICE-URL.run.app/sse"
      ]
    }
  }
}

Substitua YOUR-SERVICE-URL.run.app pela URL real do seu serviço Cloud Run.

Encontrando Sua Configuração do Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Ferramentas Disponíveis

O servidor MCP fornece estas ferramentas ao Claude:

1. calculate_route - Calcula rotas de condução ideais com tráfego
2. compare_routes - Compara múltiplas alternativas de rota
3. get_live_traffic - Obtém as condições atuais de tráfego
4. estimate_costs - Calcula custos de viagem (combustível + pedágios)

Endpoints do Serviço

• Endpoint MCP: https://your-service.run.app/sse
• Verificação de Saúde: https://your-service.run.app/health
• Estatísticas de Uso: https://your-service.run.app/stats

Desenvolvimento Local

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your API key
# GOOGLE_MAPS_API_KEY=your-api-key-here

# Start development server
npm run dev

# Test locally
npm test

Solução de Problemas

Problemas Comuns de Implantação

1. Permissão Negada

# Error: Permission denied
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

2. API Não Ativada

# Error: API not enabled
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com

3. Cobrança Não Ativada

• Visite o Console de Cobrança do GCP
• Ative a cobrança para o seu projeto

4. Chave de API Inválida

# Check API key restrictions in Console
# Ensure Directions API and Geocoding API are enabled

5. O Serviço Não Inicia

# Check logs for errors
gcloud run services logs read google-maps-mcp --region us-central1 --limit 50

Problemas Comuns em Tempo de Execução

Limite de Taxa

• Cada IP é limitado a 50 solicitações por hora
• Verifique o endpoint /stats para uso atual
• Considere implementar autenticação de usuário para limites maiores

Cota da API Excedida

• Monitore o uso da sua API do Google Maps no Console GCP
• Aumente as cotas se necessário
• Considere implementar cache para solicitações repetidas

Testando Sua Implantação

# Test health endpoint
curl "https://your-service.run.app/health"

# Test stats endpoint
curl "https://your-service.run.app/stats"

# Test with Claude Desktop
# Add the configuration and try asking Claude to calculate a route

Considerações de Segurança

• A chave de API é armazenada como variável de ambiente (segura)
• O serviço permite acesso público (nenhuma autenticação necessária)
• O limite de taxa previne abuso (50 solicitações/hora por IP)
• Nenhum dado sensível é registrado ou armazenado

Gerenciamento de Custos

• Cloud Run: Preço por solicitação
• Google Maps API: Preço por chamada de API
• Monitoramento: Use alertas de cobrança do GCP para acompanhar custos

Configure alertas de cobrança:

# Set up billing budget alerts in GCP Console
# Billing > Budgets & Alerts

Links de Documentação

• Model Context Protocol (MCP)
• Documentação do Google Cloud Run
• Documentação do Google Maps Platform
• Configuração MCP do Claude Desktop

Recursos de Suporte e Solução de Problemas

• Solução de Problemas do Cloud Run
• Solução de Problemas da API do Google Maps
• Suporte do GCP

Licença

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

Contribuição

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Teste minuciosamente
5. Envie um pull request

---

Nota: Este servidor foi projetado para fins de desenvolvimento e teste. Para uso em produção com alto tráfego, considere implementar medidas adicionais de segurança e monitoramento.