Waze MCP Server

An MCP (Model Context Protocol) server that exposes the OpenWeb Ninja Waze API to LLM hosts (Claude Desktop, Claude Code, Cursor, or any custom MCP client) as callable tools.

Each user supplies their own Waze API key at runtime via the OPENWEB_NINJA_API_KEY environment variable — no key is bundled with the server.

Tools

All location inputs are plain latitude/longitude floats. Rectangles are defined by a bottom-left (south-west) corner and a top-right (north-east) corner — the bottom-left lat/lng must both be smaller than the top-right values.

1. Get an API key

Sign up (free tier available) and create a key at https://app.openwebninja.com/api/waze. The key is sent in the x-api-key header by the client; you provide it through the OPENWEB_NINJA_API_KEY environment variable.

You can supply it in either of two ways:

• .env file (handy for local dev): copy .env.example to .env and paste your key. The server auto-loads a .env sitting next to waze_mcp_server.py. Never commit .env — it is already in .gitignore.
• Host env block (recommended when connecting to a host): set it in the host config (see step 5). A key set in the host environment overrides the .env file.

3. Verify (offline, no key needed)

Confirm the install works and all 4 tools register — no API key or network required:

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

4. Try it live with the MCP Inspector (needs a real key)

export OPENWEB_NINJA_API_KEY="your_real_key"
mcp dev waze_mcp_server.py

In the browser UI, open Tools, pick get_traffic_alerts_and_jams, enter a small bounding box (e.g. bottom-left 40.70, -74.02, top-right 40.75, -73.96), and run it. An {"error": ...} object means something went wrong — read the message (commonly an invalid key → 401, or an inverted bounding box).

5. Connect to a host

Each user puts their own key in the host's env block — not in the code.

Claude Desktop

Automatic:

mcp install waze_mcp_server.py -v OPENWEB_NINJA_API_KEY=your_real_key

Manual — edit claude_desktop_config.json and use the absolute path to the venv interpreter from step 2 (a bare python will likely fail):

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

Config file locations:

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

Restart Claude Desktop, confirm the waze tools appear, then try a prompt that forces a chain, e.g. "Any accidents or police between Times Square and JFK right now?" — the model should call 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

Or commit a project-scoped .mcp.json at the repo root:

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

Files

• openweb_ninja_waze.py — thin HTTP client for the Waze REST API (auth, retries, coord formatting).
• waze_mcp_server.py — FastMCP server defining the 4 tools.
• requirements.txt — pinned runtime dependencies (mcp[cli], requests).
• .env.example — template; copy to .env and add your key.

2. Install

Requires Python 3.10+. Use an isolated environment so the dependencies don't conflict with system packages.

Option 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

Option B — uv (faster)

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

Record the absolute path to the interpreter — you'll need it for the host config:

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

openweb_ninja_waze.py and waze_mcp_server.py must stay in the same folder — the server imports the client.

Troubleshooting