Teslamate MCP

🚀 TeslaMate MCP Server

TeslaMate MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它能够连接到你的 TeslaMate 数据库，让 AI 助手可以查询特斯拉车辆数据和分析信息，为用户提供便捷的车辆数据查询体验。

🚀 快速开始

本 MCP 服务器可连接到你的 TeslaMate PostgreSQL 数据库，并提供各种工具来检索特斯拉车辆信息、驾驶统计数据、充电数据、电池健康状况、效率指标和位置分析信息。它可与如 Claude Desktop 等兼容 MCP 的 AI 助手配合使用，支持通过自然语言查询你的特斯拉数据。

✨ 主要特性

• 连接 TeslaMate PostgreSQL 数据库，提供丰富的车辆数据查询功能。
• 支持与 MCP 兼容的 AI 助手，可通过自然语言进行数据查询。
• 提供 20 种工具，包括预定义查询工具和自定义查询工具，满足多样化的查询需求。

📦 安装指南

选项 1：本地安装

1. 克隆此仓库：

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

2. 使用 uv（推荐）安装依赖：

   uv sync
   

   或者使用 pip 安装：

   pip install -r requirements.txt
   

3. 在项目根目录创建一个 .env 文件：

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

选项 2：Docker 部署（远程访问）

对于使用 Docker 进行远程部署，可按以下步骤快速开始：

# 克隆并进入仓库
git clone https://github.com/yourusername/teslamate-mcp.git
cd teslamate-mcp

# 运行部署脚本
./deploy.sh deploy

# 或者手动操作
cp env.example .env
# 使用你的数据库凭证编辑 .env
docker-compose up -d

远程服务器将在以下地址可用：

• 可流式传输的 HTTP：http://localhost:8888/mcp

配置身份验证（可选）

若要使用承载令牌身份验证来保护你的远程 MCP 服务器，可按以下步骤操作：

1. 在 .env 文件中设置一个承载令牌：

   AUTH_TOKEN=your-secret-bearer-token-here
   

   生成一个安全的令牌：

   # 使用提供的令牌生成器
   python3 generate_token.py
   
   # 或者使用 openssl 手动生成
   openssl rand -base64 32
   
   # 或者使用其他方法创建一个安全的随机字符串
   

2. 从 MCP 客户端连接时，包含授权头：

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

3. 或者使用 curl 进行测试：

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

安全注意事项

• 生产环境使用 HTTPS：承载令牌以明文形式传输，在生产环境中始终使用 HTTPS/TLS。
• 使用强令牌：使用长且随机的令牌（至少 32 个字符）。
• 使用环境变量：切勿将令牌提交到版本控制，使用环境变量或秘密管理工具。
• 网络安全：考虑使用 VPN 或按 IP 地址限制访问以增强安全性。
• 定期轮换令牌：定期轮换你的承载令牌。

💻 使用示例

运行服务器（STDIO）

uv run python main.py

示例查询

配置好 MCP 客户端后，你可以按类别提出自然语言问题：

基本车辆信息

• "我的特斯拉基本信息是什么？"
• "显示我当前的车辆状态"
• "我的特斯拉收到了哪些软件更新？"

电池和健康

• "我的电池健康状况如何？"
• "显示我的电池随时间的损耗情况"
• "我的每日电池使用模式是怎样的？"
• "我的轮胎气压趋势如何？"

驾驶分析

• "显示我的月度驾驶总结"
• "我的每日驾驶模式是怎样的？"
• "我的最长行驶距离是多少？"
• "我总共行驶的距离和效率如何？"

效率分析

• "温度如何影响我的效率？"
• "显示按月份和温度划分的效率趋势"
• "是否有异常的电力消耗模式？"

充电和位置数据

• "我最常在哪里充电？"
• "显示我所有的充电会话总结"
• "我最常访问的地点有哪些？"

自定义 SQL 查询

• "显示数据库架构"
• "运行一个 SQL 查询，查找行驶距离超过 100 公里的行程"
• "查询按位置划分的平均充电功率"
• "查找所有在超级充电站的充电会话"

注意：run_sql 工具仅允许 SELECT 查询，为确保安全，严格禁止所有数据修改操作（INSERT、UPDATE、DELETE、DROP 等）。

📚 详细文档

可用工具

MCP 服务器提供 20 种工具用于查询你的 TeslaMate 数据：

预定义查询工具

1. get_basic_car_information - 基本车辆详细信息（VIN、型号、名称、颜色等）
2. get_current_car_status - 当前状态、位置、电池电量和温度
3. get_software_update_history - 软件更新时间线
4. get_battery_health_summary - 电池损耗和健康指标
5. get_battery_degradation_over_time - 历史电池容量趋势
6. get_daily_battery_usage_patterns - 每日电池消耗模式
7. get_tire_pressure_weekly_trends - 轮胎气压历史和趋势
8. get_monthly_driving_summary - 月度行驶距离、效率和驾驶时间
9. get_daily_driving_patterns - 每日驾驶习惯和模式
10. get_longest_drives_by_distance - 按距离排名的顶级行程详细信息
11. get_total_distance_and_efficiency - 总体驾驶统计数据
12. get_drive_summary_per_day - 每日驾驶总结
13. get_efficiency_by_month_and_temperature - 按温度进行的效率分析
14. get_average_efficiency_by_temperature - 温度对效率的影响
15. get_unusual_power_consumption - 异常电力使用检测
16. get_charging_by_location - 按位置划分的充电统计数据
17. get_all_charging_sessions_summary - 完整的充电历史总结
18. get_most_visited_locations - 经常访问的地点

自定义查询工具

19. get_database_schema - 返回完整的数据库架构（表、列、数据类型）
20. run_sql - 执行带有安全验证的自定义 SELECT 查询
    • 仅允许 SELECT 语句
    • 防止 DROP、CREATE、INSERT、UPDATE、DELETE、ALTER 等操作
    • 阻止多语句执行
    • 安全处理字符串和注释

配置

环境变量

• DATABASE_URL：用于连接你的 TeslaMate 数据库的 PostgreSQL 连接字符串

MCP 客户端配置

若要在 Claude Desktop 中使用此服务器，请在 MCP 配置文件中添加以下内容： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

本地配置（stdio 传输）

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

远程配置（可流式传输的 HTTP 传输）

若要连接到远程服务器：

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

启用身份验证时：

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

添加新查询

1. 在 queries/ 目录中创建一个新的 SQL 文件
2. 在 main.py 中添加相应的工具函数
3. 遵循现有的错误处理和数据库连接模式

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• TeslaMate - 特斯拉数据记录软件
• Model Context Protocol - AI 工具集成协议

若有 bug 报告或功能请求，请在 GitHub 上提交问题。