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 上提交問題。