Teslamate MCP README

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.

Code

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).

bash

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:

config.json

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

Terminal

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.