cobanov/teslamate-mcp

Ask your Tesla questions in plain language. Your own TeslaMate database, answered by whichever AI client you already use.

Documentation · Tool reference · Configuration · Deployment

---

TeslaMate records everything your car does into PostgreSQL, and its Grafana dashboards answer the questions someone anticipated. The interesting ones usually arrive later — is the battery actually degrading or was it just cold?, what did charging cost me at home versus on the road?, which drive was that weirdly inefficient one?

This is a Model Context Protocol server that hands that database to an AI client, so those questions get answered without you writing SQL.

You  ▸ has my battery actually degraded this year?

     ⚙ get_battery_capacity_trend(days=365)

     Usable capacity, estimated from your charging sessions rather
     than rated range:

       2025-11    53.8 kWh
       2026-02    53.1 kWh
       2026-07    52.4 kWh

     About 2.6% over eight months, which is unremarkable. The
     February dip tracks outside temperature, not capacity —
     get_average_efficiency_by_temperature shows the same shape.

• 35 tools. 30 analytics and search queries, run_sql for anything they don't cover, live schema introspection, and 3 interactive chart tools.
• Filterable, not fixed. Every report takes optional car_name, days, limit, and threshold arguments. Call one with no arguments and you get the full classic report.
• Charts in the conversation. On MCP Apps-capable clients, show_charging_curve, show_battery_degradation, and show_drive_route render self-contained SVG. Everywhere else they return the same rows.
• Read-only unless you say otherwise. run_sql executes in a READ ONLY transaction that is always rolled back. The single write tool is off by default and can only touch one column.
• Local or remote. stdio for Claude Desktop and Cursor, streamable HTTP with bearer auth for everything else.

Install

Requires a running TeslaMate with PostgreSQL, and Python 3.11+ (or just Docker).

git clone https://github.com/cobanov/teslamate-mcp.git
cd teslamate-mcp
cp env.example .env      # set DATABASE_URL
uv sync

Point your client at it — for Claude Desktop or Cursor:

{
  "mcpServers": {
    "teslamate": {
      "command": "uv",
      "args": ["--directory", "/path/to/teslamate-mcp", "run", "teslamate-mcp", "stdio"]
    }
  }
}

Ask it something. teslamate-mcp list-tools prints everything it found.

Remote

docker run -d -p 8888:8888 \
  -e DATABASE_URL='postgresql://teslamate:…@host:5433/teslamate' \
  -e AUTH_TOKEN="$(uv run teslamate-mcp gen-token | cut -d= -f2)" \
  ghcr.io/cobanov/teslamate-mcp:latest

The endpoint is /mcp, the probe is /health. Multi-arch images (amd64, arm64) ship with every release.

This database is your location history. Keep it on a private network — a VPN or Tailscale — rather than the open internet. Deployment covers the options.

Documentation

Everything beyond this page lives in the wiki:

Tool Reference	All 35 tools, their parameters, what each returns
Configuration	Every environment variable, with guidance
Deployment	Docker, images, proxies, exposure, troubleshooting
Writing Queries	Add your own tool with a .sql + .toml pair — no Python
Write Tools	The opt-in charging-cost write path and its grant
Development	Setup, tests, layout, releasing

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Adding a query needs no Python at all: drop a .sql file and a .toml sidecar into src/teslamate_mcp/queries/ and the registry picks it up.

A large part of the 0.9 feature line — typed parameters, twelve new queries, MCP Apps, and the SDK v2 migration — was contributed by @batubozkan.

License

MIT — see LICENSE.