Waze Server

CI License: MIT

A small Model Context Protocol server that exposes Waze routing and travel-time tools to MCP clients (Claude Desktop, Claude Code, VS Code, Cursor, …).

It uses the free pywaze library, which talks to Waze's public livemap endpoints directly — the same library Home Assistant's "Waze Travel Time" integration uses. No API key, no third-party proxy, no cost.

Tools

Tool	Description
get_travel_time	Fastest-route duration + distance between two locations
get_routes	Up to N alternative routes, each with street names
geocode_address	Resolve an address to latitude/longitude

origin / destination accept a street address or "lat,lng" coordinates. Optional params: region (US, NA, EU, IL, AU), vehicle_type (car, taxi, motorcycle), avoid_toll_roads, avoid_ferries, real_time.

All tools are read-only (advertised via MCP tool annotations) and return structured output (typed JSON). Identical lookups are cached briefly to spare Waze's endpoints (see Configuration).

Requirements

• Python 3.10+ — pywaze and mcp require it. (On macOS the system Python 3.9 will not work; install a newer one, e.g. via Homebrew or python.org.)

Setup

python3 -m venv .venv          # use a Python 3.10+ interpreter
./.venv/bin/pip install -r requirements.txt

Or install it as a package (uses pyproject.toml), which also adds a waze-mcp command:

./.venv/bin/pip install -e .

On Windows, the interpreter is .venv\Scripts\python.exe instead of .venv/bin/python.

Configuration

All settings are optional and set via environment variables:

Variable	Default	Purpose
WAZE_MCP_REGION	EU	Default region (US/NA/EU/IL/AU) when a call omits it
WAZE_MCP_TIMEOUT	60	Per-request timeout (seconds) to Waze
WAZE_MCP_CACHE_TTL	60	Seconds to cache identical lookups (0 disables)
WAZE_MCP_AUTH_TOKEN	—	If set, HTTP requests must send Authorization: Bearer <token>
WAZE_MCP_TRANSPORT	stdio	Default transport (stdio/streamable-http/sse)
WAZE_MCP_HOST / WAZE_MCP_PORT	127.0.0.1 / 8000	HTTP bind address

CLI flags (--transport, --host, --port, --auth-token) override the matching environment variable.

Run

./.venv/bin/python server.py

The server speaks MCP over stdio, so it is normally launched by your MCP client rather than run by hand. Use the configs below.

In the client configs below, replace /path/to/waze-mcp with the absolute path to your clone.

Run over HTTP (remote hosts)

By default the server uses stdio. To let a remote host connect over HTTP — for example Microsoft Scout's Remote / Local URL mode — start it with the streamable-http transport:

./.venv/bin/python server.py --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is served at http://<host>:<port>/mcp, and an unauthenticated http://<host>:<port>/health endpoint returns ok for liveness checks.

Optional bearer-token auth — require a token on every request (the /health endpoint stays open):

WAZE_MCP_AUTH_TOKEN=secret \
  ./.venv/bin/python server.py --transport streamable-http --host 0.0.0.0 --port 8000
# or pass --auth-token secret

Clients then send Authorization: Bearer secret (e.g. Scout's Bearer token field).

Without a token the HTTP endpoint is unauthenticated. Keep it bound to 127.0.0.1, or set a token and/or place it behind a reverse proxy with TLS when exposing it beyond localhost.

Docker

docker build -t waze-mcp .
docker run -p 8000:8000 waze-mcp                                 # http://localhost:8000/mcp
docker run -p 8000:8000 -e WAZE_MCP_AUTH_TOKEN=secret waze-mcp   # with auth

The image runs the streamable-http transport on 0.0.0.0:8000 and ships a /health healthcheck.

VS Code

Add to .vscode/mcp.json (workspace) or your user mcp.json:

{
  "servers": {
    "waze": {
      "type": "stdio",
      "command": "/path/to/waze-mcp/.venv/bin/python",
      "args": ["/path/to/waze-mcp/server.py"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "waze": {
      "command": "/path/to/waze-mcp/.venv/bin/python",
      "args": ["/path/to/waze-mcp/server.py"]
    }
  }
}

Claude Code (CLI)

claude mcp add waze -- \
  "/path/to/waze-mcp/.venv/bin/python" \
  "/path/to/waze-mcp/server.py"

Notes & caveats

• Unofficial data source. Waze has no official public API. pywaze calls Waze's internal livemap endpoints — the same ones the website uses. They can change or be rate-limited without notice, and heavy use may be against Waze's Terms of Service.
• Regions. EU covers Europe; use US/NA for North America, IL for Israel, AU for Australia. Default is EU.
• Privacy. Origin/destination coordinates are sent only to waze.com. The HTTP client's request logging is quieted to WARNING, so addresses/coordinates are not written to the logs by default.

Development

./.venv/bin/pip install -e ".[dev]"   # pytest, pytest-asyncio, ruff
./.venv/bin/ruff check .
./.venv/bin/pytest -q                  # tests mock Waze — no network needed

See CONTRIBUTING.md. CI runs ruff + pytest on Python 3.10–3.13.

Security

The server is read-only and needs no credentials. For the HTTP transport's auth and hardening notes, see SECURITY.md.

Credits

• Routing/geocoding by pywaze (Kevin Stillhammer), based on WazeRouteCalculator.
• "Powered by Waze."

License

MIT © 2026 Serge Michaux