teslamate

TeslaMate MCP Server exposes a set of predefined and custom SQL-based tools that bridge your TeslaMate PostgreSQL data with AI assistants via the Model Context Protocol. It offers 18 predefined queries covering vehicle information, battery health, driving analytics, efficiency, charging/location, and two custom query tools for viewing the database schema and running read-only SQL. You can query real-time vehicle status, historical trends, and location-based charging patterns, all through natural language prompts that map to the underlying SQL tools. For remote deployments, you can enable optional authentication using a bearer token to restrict access; all data access remains read-only and subject to SQL validation. To use the server, run it locally with uv (or deploy via Docker) and point your MCP client to the server endpoint. The tools will appear as named capabilities (e.g., get_current_car_status, get_battery_health_summary, get_monthly_driving_summary, run_sql) that you can invoke from your AI assistant. If you add new queries, place an SQL file in queries/, update src/tools.py with a ToolDefinition referencing the SQL file, and restart the server so the tool registers automatically.

Prerequisites:

• Python 3.11+ (for local development) or Docker for remote deployment
• TeslaMate running with PostgreSQL
• Access to the repository for cloning

Local (Development) setup:

# 1) Clone the MCP server repository
git clone https://github.com/cobanov/teslamate-mcp.git
cd teslamate-mcp

# 2) Create and edit environment variables
cp env.example .env
# Edit .env to configure DATABASE_URL and optional AUTH_TOKEN

Run locally (via uv):

# Ensure dependencies are installed (virtual environment recommended)
python -m pip install -r requirements.txt

# Start the MCP server locally
uv sync

Remote/Docker setup (recommended for remote deployments):

# 1) Clone and configure
git clone https://github.com/cobanov/teslamate-mcp.git
cd teslamate-mcp
cp env.example .env
# Edit .env with your DATABASE_URL and optional AUTH_TOKEN

# 2) Use Docker-based deployment (Docker Compose is commonly supported)
docker-compose up -d

Server access:

• Local: http://localhost:8888/mcp
• Remote: depends on Docker deployment and networking

Note: If you want to run the local server without uv, you can adapt the command in mcp_config to your preferred runner, but the provided example uses uv for local development.

Tips and common issues:

• Ensure the DATABASE_URL in .env correctly points to your TeslaMate PostgreSQL instance and that the database is accessible from the MCP server host.
• If you enable AUTH_TOKEN for remote access, set the token in the environment and provide it to MCP clients accordingly.
• When adding new queries, place the SQL file in queries/ and register it in src/tools.py (ToolDefinition) so the tool is auto-registered on restart.
• The server is read-only by default; only SELECT queries are allowed due to validation rules. Use run_sql for custom read-only queries and view the schema with get_database_schema.
• For production, enable HTTPS and consider placing the MCP server behind a reverse proxy for TLS termination.