README - teslamate-mcp by cobanov

TeslaMate MCP Server

A Model Context Protocol (MCP) server that provides access to your TeslaMate database, allowing AI assistants to query Tesla vehicle data and analytics.

Overview

This MCP server connects to your TeslaMate PostgreSQL database and exposes various tools to retrieve Tesla vehicle information, driving statistics, charging data, battery health, efficiency metrics, and location analytics. It's designed to work with MCP-compatible AI assistants like Claude Desktop, enabling natural language queries about your Tesla data.

Prerequisites

TeslaMate running with a PostgreSQL database
Python 3.11 or higher
Access to your TeslaMate database

Installation

Option 1: Local Installation

Clone this repository:

git clone https://github.com/yourusername/teslamate-mcp.git
cd teslamate-mcp

Install dependencies using uv (recommended):
```
uv sync
```
Or using pip:
```
pip install -r requirements.txt
```

Create a .env file in the project root:

DATABASE_URL=postgresql://username:password@hostname:port/teslamate

Option 2: Docker Deployment (Remote Access)

For remote deployment using Docker. Quick start:

# Clone and navigate to the repository
git clone https://github.com/yourusername/teslamate-mcp.git
cd teslamate-mcp

# Run the deployment script
./deploy.sh deploy

# Or manually:
cp env.example .env
# Edit .env with your database credentials
docker-compose up -d

The remote server will be available at:

Streamable HTTP: http://localhost:8888/mcp

Configuring Authentication (Optional)

To secure your remote MCP server with bearer token authentication:

Set a bearer token in your .env file:

AUTH_TOKEN=your-secret-bearer-token-here

Generate a secure token:

# Use the provided token generator
python3 generate_token.py

# Or generate manually with openssl
openssl rand -base64 32

# Or use any other method to create a secure random string

When connecting from MCP clients, include the Authorization header:

{
  "mcpServers": {
    "teslamate-remote": {
      "url": "http://your-server:8888/mcp",
      "transport": "streamable_http",
      "headers": {
        "Authorization": "Bearer your-secret-bearer-token-here"
      }
    }
  }
}

Or use curl for testing:

curl -H "Authorization: Bearer your-secret-bearer-token-here" \
     http://localhost:8888/mcp

Security Considerations

Use HTTPS in production: Bearer tokens are sent in plain text. Always use HTTPS/TLS in production environments.
Strong tokens: Use long, random tokens (at least 32 characters).
Environment variables: Never commit tokens to version control. Use environment variables or secrets management.
Network security: Consider using a VPN or restricting access by IP address for additional security.
Token rotation: Regularly rotate your bearer tokens.

Available Tools

The MCP server provides 20 tools for querying your TeslaMate data:

Pre-defined Query Tools

get_basic_car_information - Basic vehicle details (VIN, model, name, color, etc.)
get_current_car_status - Current state, location, battery level, and temperature
get_software_update_history - Timeline of software updates
get_battery_health_summary - Battery degradation and health metrics
get_battery_degradation_over_time - Historical battery capacity trends
get_daily_battery_usage_patterns - Daily battery consumption patterns
get_tire_pressure_weekly_trends - Tire pressure history and trends
get_monthly_driving_summary - Monthly distance, efficiency, and driving time
get_daily_driving_patterns - Daily driving habits and patterns
get_longest_drives_by_distance - Top drives by distance with details
get_total_distance_and_efficiency - Overall driving statistics
get_drive_summary_per_day - Daily drive summaries
get_efficiency_by_month_and_temperature - Efficiency analysis by temperature
get_average_efficiency_by_temperature - Temperature impact on efficiency
get_unusual_power_consumption - Anomalous power usage detection
get_charging_by_location - Charging statistics by location
get_all_charging_sessions_summary - Complete charging history summary
get_most_visited_locations - Frequently visited places

Custom Query Tools

get_database_schema - Returns complete database schema (tables, columns, data types)
run_sql - Execute custom SELECT queries with safety validation
- Only SELECT statements allowed
- Prevents DROP, CREATE, INSERT, UPDATE, DELETE, ALTER, etc.
- Blocks multiple statement execution
- Safely handles strings and comments

Configuration

Environment Variables

DATABASE_URL: PostgreSQL connection string for your TeslaMate database

MCP Client Configuration

To use this server with Claude Desktop, add the following to your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Local Configuration (stdio transport)

{
  "mcpServers": {
    "teslamate": {
      "command": "uv",
      "args": ["run", "python", "/path/to/teslamate-mcp/main.py"],
      "env": {
        "DATABASE_URL": "postgresql://username:password@hostname:port/teslamate"
      }
    }
  }
}

Remote Configuration (streamable HTTP transport)

For connecting to a remote server:

{
  "mcpServers": {
    "TeslaMate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://your-private-server:8888/mcp",
        "--allow-http"
      ]
    }
  }
}

With authentication enabled:

{
  "mcpServers": {
    "TeslaMate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://your-private-server:8888/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <secret bearer token>"
      }
    }
  }
}

Usage

Running the Server (STDIO)

uv run python main.py

Example Queries

Once configured with an MCP client, you can ask natural language questions organized by category:

Basic Vehicle Information

"What's my Tesla's basic information?"
"Show me my current car status"
"What software updates has my Tesla received?"

Battery and Health

"How is my battery health?"
"Show me battery degradation over time"
"What are my daily battery usage patterns?"
"How are my tire pressures trending?"

Driving Analytics

"Show me my monthly driving summary"
"What are my daily driving patterns?"
"What are my longest drives by distance?"
"What's my total distance driven and efficiency?"

Efficiency Analysis

"How does temperature affect my efficiency?"
"Show me efficiency trends by month and temperature"
"Are there any unusual power consumption patterns?"

Charging and Location Data

"Where do I charge most frequently?"
"Show me all my charging sessions summary"
"What are my most visited locations?"

Custom SQL Queries

"Show me the database schema"
"Run a SQL query to find drives longer than 100km"
"Query the average charging power by location"
"Find all charging sessions at superchargers"

Note: The run_sql tool only allows SELECT queries. All data modification operations (INSERT, UPDATE, DELETE, DROP, etc.) are strictly forbidden for safety.

Adding New Queries

Create a new SQL file in the queries/ directory
Add a corresponding tool function in main.py
Follow the existing pattern for error handling and database connections

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

TeslaMate - Tesla data logging software
Model Context Protocol - Protocol for AI-tool integration

For bugs and feature requests, please open an issue on GitHub.