Waze MCP server

Servidor MCP Waze

Um servidor MCP (Model Context Protocol) que expõe a API Waze do OpenWeb Ninja a hosts de LLM (Claude Desktop, Claude Code, Cursor ou qualquer cliente MCP personalizado) como ferramentas chamáveis.

Cada usuário fornece sua própria chave de API Waze em tempo de execução por meio da variável de ambiente OPENWEB_NINJA_API_KEY — nenhuma chave é incluída no servidor.

Ferramentas

Ferramenta	O que faz
get_traffic_alerts_and_jams	Alertas em tempo real (acidente, polícia, perigo, via fechada…) e engarrafamentos dentro de um retângulo geográfico.
get_driving_directions	Rotas de direção entre dois pontos, incluindo alertas ao longo de cada rota.
search_venues	Locais / pontos de interesse dentro de um retângulo geográfico.
autocomplete_places	Autocompletar para lugares, endereços e POIs (útil para converter texto em coordenadas antes de traçar rotas).

Todas as entradas de localização são pares simples de latitude/longitude float. Retângulos são definidos por um canto inferior esquerdo (sudoeste) e um canto superior direito (nordeste) — a latitude/longitude do canto inferior esquerdo deve ser menor que os valores do canto superior direito.

1. Obtenha uma chave de API

Cadastre-se (há plano gratuito disponível) e crie uma chave em https://app.openwebninja.com/api/waze. A chave é enviada no cabeçalho x-api-key pelo cliente; você a fornece por meio da variável de ambiente OPENWEB_NINJA_API_KEY.

Você pode fornecê-la de duas maneiras:

• Arquivo .env (prático para desenvolvimento local): copie .env.example para .env e cole sua chave. O servidor carrega automaticamente um .env localizado ao lado de waze_mcp_server.py. Nunca envie .env para o repositório — ele já está em .gitignore.
• Bloco env do host (recomendado ao conectar a um host): defina-o na configuração do host (veja o passo 5). Uma chave definida no ambiente do host substitui o arquivo .env.

2. Instalação

Requer Python 3.10+. Use um ambiente isolado para que as dependências não entrem em conflito com os pacotes do sistema.

Opção A — venv + pip

cd /path/to/WazeMCP
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt   # or: pip install "mcp[cli]" requests

Opção B — uv (mais rápido)

cd /path/to/WazeMCP
uv venv
uv pip install -r requirements.txt   # or: uv pip install "mcp[cli]" requests

Anote o caminho absoluto do interpretador — você precisará dele para a configuração do host:

python3 -c "import sys; print(sys.executable)"
# e.g. /path/to/WazeMCP/.venv/bin/python

openweb_ninja_waze.py e waze_mcp_server.py devem permanecer na mesma pasta — o servidor importa o cliente.

3. Verificação (offline, sem chave necessária)

Confirme que a instalação funciona e que as 4 ferramentas são registradas — sem chave de API ou rede:

python3 -c "import asyncio, waze_mcp_server as s; print(len(asyncio.run(s.mcp.list_tools())), 'tools registered')"
# -> 4 tools registered

4. Teste ao vivo com o MCP Inspector (requer chave real)

export OPENWEB_NINJA_API_KEY="your_real_key"
mcp dev waze_mcp_server.py

Na interface do navegador, abra Ferramentas, selecione get_traffic_alerts_and_jams, insira uma caixa delimitadora pequena (ex.: canto inferior esquerdo 40.70, -74.02, canto superior direito 40.75, -73.96) e execute. Um objeto {"error": ...} significa que algo deu errado — leia a mensagem (comumente uma chave inválida → 401, ou uma caixa delimitadora invertida).

5. Conecte a um host

Cada usuário coloca sua própria chave no bloco env do host — não no código.

Claude Desktop

Automático:

mcp install waze_mcp_server.py -v OPENWEB_NINJA_API_KEY=your_real_key

Manual — edite claude_desktop_config.json e use o caminho absoluto do interpretador do venv do passo 2 (um python simples provavelmente falhará):

{
  "mcpServers": {
    "waze": {
      "command": "/path/to/WazeMCP/.venv/bin/python",
      "args": ["/path/to/WazeMCP/waze_mcp_server.py"],
      "env": { "OPENWEB_NINJA_API_KEY": "your_real_key" }
    }
  }
}

Locais dos arquivos de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Reinicie o Claude Desktop, confirme que as ferramentas waze aparecem e tente um prompt que force uma cadeia, ex.: "Há acidentes ou polícia entre Times Square e JFK agora?" — o modelo deve chamar autocomplete_places → get_driving_directions → get_traffic_alerts_and_jams.

Claude Code (CLI)

claude mcp add waze \
  -e OPENWEB_NINJA_API_KEY=your_real_key \
  -- /path/to/WazeMCP/.venv/bin/python /path/to/WazeMCP/waze_mcp_server.py

Ou envie um .mcp.json no escopo do projeto na raiz do repositório:

{
  "mcpServers": {
    "waze": {
      "command": "/path/to/WazeMCP/.venv/bin/python",
      "args": ["/path/to/WazeMCP/waze_mcp_server.py"],
      "env": { "OPENWEB_NINJA_API_KEY": "your_real_key" }
    }
  }
}

Solução de problemas

Sintoma	Causa	Correção
ModuleNotFoundError: No module named 'mcp'	Servidor iniciado com um interpretador sem as dependências	Aponte command para o interpretador do venv onde você instalou mcp/requests.
ModuleNotFoundError: No module named 'openweb_ninja_waze'	Arquivo do cliente não está junto ao servidor, ou iniciado de outro diretório de trabalho	Mantenha ambos os arquivos .py na mesma pasta.
Erro pip: Cannot uninstall <pkg> ... installed by debian	Instalação em um Python gerenciado pelo sistema	Use um venv ou uv.
Ferramenta retorna {"error": "...", "status_code": 401}	Chave de API ausente ou inválida	Defina OPENWEB_NINJA_API_KEY no bloco env do host (não apenas no seu shell).
Resultados vazios para uma área claramente movimentada	Caixa delimitadora invertida	Garanta que a latitude/longitude do canto inferior esquerdo sejam menores que as do canto superior direito.
Host não mostra ferramentas	JSON inválido na configuração, ou host não reiniciado	Valide o JSON; reinicie completamente o host.

Arquivos

• openweb_ninja_waze.py — cliente HTTP leve para a API REST do Waze (autenticação, tentativas, formatação de coordenadas).
• waze_mcp_server.py — servidor FastMCP que define as 4 ferramentas.
• requirements.txt — dependências de runtime fixadas (mcp[cli], requests).
• .env.example — modelo; copie para .env e adicione sua chave.