TeslaMate MCP Server

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:

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

2. Add the server to your MCP client. Example for Claude Desktop or Cursor:

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

Quick start — Docker

cp env.example .env          # set DATABASE_URL, and set AUTH_TOKEN for remote use
docker compose up -d

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:

docker run --rm -e DATABASE_URL=... -p 8888:8888 ghcr.io/cobanov/teslamate-mcp:latest

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.

Tools

Each report tool accepts optional filters: car_name everywhere, plus days, limit, and thresholds where they apply. A call with no arguments returns the full report.

Tools return metric values (km, km/h, °C, bar, m) and rated range. get_unit_preferences reads the units chosen in TeslaMate's settings (km or mi, °C or °F, bar or psi, rated or ideal range) so the assistant can convert when it answers; the charts stay metric.

The server also sends MCP instructions: how to read units, time zones and costs, and which tool answers which kind of question.

Reports (22)

Insights (8)

Timeline and car state (3)

TeslaMate logs whether each car is online, asleep, or offline. get_current_car_status reads that log too, and reports whether the car is driving, charging, online, asleep, or offline right now.

Search and detail (5)