cobanov/teslamate-mcp

Connect your AI assistant to your TeslaMate data.
This is a Model Context Protocol (MCP) server. It reads your TeslaMate PostgreSQL database. It gives MCP clients (Claude Desktop, Cursor, and others) 57 tools, 11 prompts, and interactive charts.
**Documentation** · Tool reference · Configuration · Deployment
What you can ask
- "Is my battery really degrading?" — the server estimates usable capacity in kWh from your charging sessions.
- "How much range do I lose while parked?" — the server finds vampire drain between drives.
- "Show the route of my longest drive." — the server returns the GPS track, with an interactive map on chart-capable clients.
- "Compare my driving this month with last month." — one call returns both windows, per metric.
- "Can I reach Ankara (450 km) at 5°C without charging?" — the server estimates the arrival battery % from your own drives at that temperature.
- "Why isn't my car sleeping?" — the server reads TeslaMate's state log and lists the periods the car stayed awake while parked.
- "What did my car do on Saturday?" — one call returns the drives, charges, and parked time in order.
Highlights
- **47 SQL report tools.** Battery capacity and degradation, sleep and state history, a timeline of each day, trips, range estimates, fast-charging speeds, charging costs (with estimates for missing ones) and fuel savings, elevation, vampire drain, geofences, driving patterns, routes, and search tools for drives and charging sessions.
- **8 interactive charts (MCP Apps).** Charging curves (one session, or several overlaid), battery degradation, drive and trip maps with elevation profiles, a monthly or yearly activity dashboard, a map of visited places, and consumption against temperature. On clients without chart support, the same tools return plain rows.
- **Guidance for the assistant.** MCP instructions and 11 prompts map questions to tools, and get_unit_preferences lets the assistant answer in the units set in TeslaMate.
- **Typed inputs and outputs.** Each report tool declares its parameters and result columns in a .toml file. The server validates the declarations at startup. Parameters bind as SQL placeholders, never as string concatenation.
- **Safe custom SQL.** run_sql runs your SELECT inside a PostgreSQL READ ONLY transaction, with timeouts and a row cap. The transaction always rolls back.
- **Optional cost writes, with confirmation.** One opt-in tool writes charging costs. A column-scoped database grant limits what it can touch. Clients with MCP elicitation show a confirmation dialog first.
- **Local-time reports.** Set REPORT_TIMEZONE and daily, weekly, and monthly buckets follow your local midnight.
- **Two transports.** Run teslamate-mcp stdio for local clients. Run teslamate-mcp http for remote clients, with bearer-token auth and a /health probe.
Requirements
- TeslaMate with its PostgreSQL database.
- Python 3.11+ for a local install, or Docker for a server install.
Quick start — local (stdio)
1. Install:
2. Add the server to your MCP client. Example for Claude Desktop or Cursor:
Quick start — Docker
The MCP endpoint is http://localhost:8888/mcp. The health probe is http://localhost:8888/health. It runs a SELECT 1 against the database and returns 503 when the database is unreachable.
A multi-arch image (linux/amd64, linux/arm64) is published to GHCR on each release:
Deploy on Unraid, behind Cloudflare
You can reach this server from claude.ai, Claude Desktop, and mobile — with OAuth login and with no open ports on your home network.
The **Unraid + Cloudflare deployment guide** shows the full path:
1. Run the container on Unraid with the included Community Apps template.
2. Publish it through a Cloudflare Tunnel. No inbound firewall rules are necessary.
3. Put a Cloudflare Zero Trust **MCP Server Portal** in front. The portal handles OAuth for Claude clients and sends the bearer token upstream.
The guide includes the exact dashboard fields, verification commands for each phase, and a troubleshooting table.
> The portal rewrites ui:// resource URIs, so the interactive charts (show_* tools) do not render through it. To get them, connect Claude through Cloudflare Access directly. The guide's direct connection section shows how.