Waze MCP server

Waze MCP Server

Un servidor MCP (Model Context Protocol) que expone la API de Waze de OpenWeb Ninja a los hosts de LLM (Claude Desktop, Claude Code, Cursor o cualquier cliente MCP personalizado) como herramientas invocables.

Cada usuario proporciona su propia clave de API de Waze en tiempo de ejecución mediante la variable de entorno OPENWEB_NINJA_API_KEY — no se incluye ninguna clave con el servidor.

Herramientas

Herramienta	Qué hace
get_traffic_alerts_and_jams	Alertas en tiempo real (accidente, policía, peligro, carretera cerrada…) y atascos dentro de un rectángulo geográfico.
get_driving_directions	Rutas de conducción entre dos puntos, incluyendo alertas a lo largo de cada ruta.
search_venues	Lugares / puntos de interés dentro de un rectángulo geográfico.
autocomplete_places	Autocompletado de lugares, direcciones y POIs (útil para convertir texto en coordenadas antes de enrutar).

Todas las entradas de ubicación son coordenadas de latitud/longitud float simples. Los rectángulos se definen por una esquina inferior-izquierda (suroeste) y una esquina superior-derecha (noreste) — la lat/lng inferior-izquierda debe ser menor que los valores superior-derecha.

1. Obtener una clave de API

Regístrate (hay plan gratuito disponible) y crea una clave en https://app.openwebninja.com/api/waze. La clave se envía en el encabezado x-api-key por el cliente; la proporcionas a través de la variable de entorno OPENWEB_NINJA_API_KEY.

Puedes proporcionarla de dos maneras:

• Archivo .env (práctico para desarrollo local): copia .env.example a .env y pega tu clave. El servidor carga automáticamente un .env que se encuentre junto a waze_mcp_server.py. Nunca hagas commit de .env — ya está en .gitignore.
• Bloque env del host (recomendado al conectarse a un host): configúralo en la configuración del host (ver paso 5). Una clave configurada en el entorno del host anula el archivo .env.

2. Instalación

Requiere Python 3.10+. Usa un entorno aislado para que las dependencias no entren en conflicto con los paquetes del sistema.

Opción 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

Opción B — uv (más rápido)

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

Anota la ruta absoluta al intérprete — la necesitarás para la configuración del host:

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

openweb_ninja_waze.py y waze_mcp_server.py deben permanecer en la misma carpeta — el servidor importa el cliente.

3. Verificación (sin conexión, no se necesita clave)

Confirma que la instalación funciona y que las 4 herramientas se registran — no se requiere clave de API ni red:

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

4. Pruébalo en vivo con el MCP Inspector (necesita una clave real)

export OPENWEB_NINJA_API_KEY="your_real_key"
mcp dev waze_mcp_server.py

En la interfaz del navegador, abre Tools, selecciona get_traffic_alerts_and_jams, introduce un cuadro delimitador pequeño (p. ej. inferior-izquierda 40.70, -74.02, superior-derecha 40.75, -73.96) y ejecútalo. Un objeto {"error": ...} significa que algo salió mal — lee el mensaje (comúnmente una clave inválida → 401, o un cuadro delimitador invertido).

5. Conectarse a un host

Cada usuario pone su propia clave en el bloque env del host — no en el código.

Claude Desktop

Automático:

mcp install waze_mcp_server.py -v OPENWEB_NINJA_API_KEY=your_real_key

Manual — edita claude_desktop_config.json y usa la ruta absoluta al intérprete del venv del paso 2 (un python simple probablemente fallará):

{
  "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" }
    }
  }
}

Ubicaciones de los archivos de configuración:

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

Reinicia Claude Desktop, confirma que aparecen las herramientas waze, y luego prueba un prompt que fuerce una cadena, p. ej. "¿Hay accidentes o policía entre Times Square y JFK ahora mismo?" — el modelo debería llamar a 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

O haz commit de un .mcp.json a nivel de proyecto en la raíz del repositorio:

{
  "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" }
    }
  }
}

Solución de problemas

Síntoma	Causa	Solución
ModuleNotFoundError: No module named 'mcp'	El servidor se lanzó con un intérprete que no tiene las dependencias	Apunta command al intérprete del venv donde instalaste mcp/requests.
ModuleNotFoundError: No module named 'openweb_ninja_waze'	El archivo del cliente no está junto al servidor, o se lanzó desde otro directorio de trabajo	Mantén ambos archivos .py en una misma carpeta.
Error pip: Cannot uninstall <pkg> ... installed by debian	Instalación en un Python gestionado por el sistema	Usa un venv o uv.
La herramienta devuelve {"error": "...", "status_code": 401}	Clave de API faltante o inválida	Configura OPENWEB_NINJA_API_KEY en el bloque env del host (no solo en tu shell).
Resultados vacíos en una zona claramente concurrida	Cuadro delimitador invertido	Asegúrate de que la lat/lng inferior-izquierda sea menor que la superior-derecha.
El host no muestra herramientas	JSON mal formado en la configuración, o el host no se reinició	Valida el JSON; reinicia el host por completo.

Archivos

• openweb_ninja_waze.py — cliente HTTP ligero para la API REST de Waze (autenticación, reintentos, formato de coordenadas).
• waze_mcp_server.py — servidor FastMCP que define las 4 herramientas.
• requirements.txt — dependencias de ejecución fijadas (mcp[cli], requests).
• .env.example — plantilla; copia a .env y añade tu clave.