ev-energy-mcp

MCP server that estimates the kWh required to drive an EV between two waypoints, using a calibrated physics road-load model integrated along the actual routed polyline (including elevation).

See docs/ for the physics model, vehicle parameter sources, and backend notes. See CLAUDE.md for the working agreement.

MVP

• Routing: OpenRouteService (returns elevation natively from SRTM).
• Elevation: pluggable — ORS (SRTM, default) or Google Elevation (fused/smoothed DEM, recommended for mountain routes). Set ELEVATION_BACKEND=google and GOOGLE_MAPS_KEY=… in .env to enable.
• Vehicle profiles: Tesla Model Y LR, Tesla Model 3 LR, BYD Yuan Up.
• Waypoints are latitude/longitude only — geocoding (address → lat/lon) is out of scope for the MVP.

Install

git clone <repo-url> ev-energy-mcp
cd ev-energy-mcp
uv sync --extra dev      # or: python -m venv .venv && pip install -e .[dev]
cp .env.example .env
# edit .env and set ORS_API_KEY (free at https://openrouteservice.org/dev/)

Run tests

uv run pytest

Run standalone

uv run ev-energy-mcp

Connect to Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ev-energy": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/ev-energy-mcp",
        "run",
        "ev-energy-mcp"
      ],
      "env": {
        "ORS_API_KEY": "your-openrouteservice-key",
        "ELEVATION_BACKEND": "google",
        "GOOGLE_MAPS_KEY": "your-google-maps-key"
      }
    }
  }
}

You may need the absolute path to uv in the command field — which uv (macOS/Linux) or where uv (Windows). Restart Claude Desktop; calculate_energy and list_ev_profiles will appear in the tools menu.

Example prompt:

Using the Tesla Model 3 Long Range, how much energy will I use driving from (37.7749, -122.4194) to (34.0522, -118.2437)?