teslamate-mcp

MCP server built from skeleton-mcp that exposes TeslaMate HTTP APIs.

What This Server Exposes

TeslaMate endpoints covered by dedicated tools:

• GET /health_check
• PUT /api/car/:id/logging/suspend
• PUT /api/car/:id/logging/resume
• GET /drive/:id/gpx

Additional MCP tools:

• teslamate_connection_info
• teslamate_scope_info
• teslamate_list_endpoints
• teslamate_api_request (generic passthrough to support all currently available TeslaMate routes)

Tool Catalog

• teslamate_connection_info

  • Returns MCP and TeslaMate connection/auth configuration status (without leaking secrets).

• teslamate_list_endpoints

  • Returns the currently known TeslaMate routes from TeslaMate docs/source.

• teslamate_scope_info

  • Returns the effective user scope used to resolve TeslaMate connection settings.

• teslamate_health_check

  • Calls GET /health_check.
  • Optional userId routes the call to a specific TeslaMate user profile.

• teslamate_suspend_logging

  • Calls PUT /api/car/:id/logging/suspend.
  • Optional userId routes the call to a specific TeslaMate user profile.
  • Requires authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

• teslamate_resume_logging

  • Calls PUT /api/car/:id/logging/resume.
  • Optional userId routes the call to a specific TeslaMate user profile.
  • Requires authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

• teslamate_get_drive_gpx

  • Calls GET /drive/:id/gpx.
  • Optional userId routes the call to a specific TeslaMate user profile.

• teslamate_api_request

  • Generic TeslaMate request tool with method/path/query/body/headers support.
  • Optional userId routes the call to a specific TeslaMate user profile.
  • Uses the configured TeslaMate base URL and auth mode.
  • Mutating methods (POST, PUT, PATCH, DELETE) require authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

Environment

Copy .env.example to .env and set at least:

• TESLAMATE_BASE_URL (default http://127.0.0.1:4000)
• TESLAMATE_AUTH_MODE (none, bearer, or basic)
• TESLAMATE_BEARER_TOKEN if using bearer auth
• TESLAMATE_BASIC_USERNAME and TESLAMATE_BASIC_PASSWORD if using basic auth

Optional security control for mutating MCP operations:

• MCP_ADMIN_AUTH_KEY

Multi-user TeslaMate routing:

• MCP_CONFIG_DEFAULT_USER_ID sets the default profile (default when unset).
• TESLAMATE_USER_OVERRIDES_JSON is a JSON object keyed by user id with per-user TeslaMate overrides.
• For HTTP mode with Vault token auth, authenticated token metadata userId is used as request scope automatically.

Example TESLAMATE_USER_OVERRIDES_JSON:

{
  "default": {
    "baseUrl": "http://teslamate-default:4000",
    "authMode": "none"
  },
  "user-123": {
    "baseUrl": "http://teslamate-user-123:4000",
    "authMode": "bearer",
    "bearerToken": "token-for-user-123"
  }
}

HTTP auth modes and sources:

• MCP_HTTP_AUTH_MODE supports token, oauth2, or both.
• MCP_HTTP_TOKEN_SOURCE=env keeps static tokens from MCP_HTTP_AUTH_TOKENS.
• MCP_HTTP_TOKEN_SOURCE=vault validates bearer tokens from Vault token index and can resolve authenticated userId.
• MCP_HTTP_VAULT_TOKEN_INDEX_PATH, MCP_HTTP_VAULT_TOKEN_DEFAULT_USER_ID, MCP_HTTP_VAULT_TOKEN_REQUIRED_SCOPES, MCP_HTTP_VAULT_TOKEN_REQUIRED_AUDIENCE, MCP_HTTP_VAULT_TOKEN_CACHE_TTL_MS configure Vault token verification.
• MCP_HTTP_OAUTH2_INTROSPECTION_URL, MCP_HTTP_OAUTH2_CLIENT_ID, MCP_HTTP_OAUTH2_CLIENT_SECRET, MCP_HTTP_OAUTH2_REQUIRED_SCOPES, MCP_HTTP_OAUTH2_REQUIRED_AUDIENCE, MCP_HTTP_OAUTH2_TIMEOUT_MS, MCP_HTTP_OAUTH2_CACHE_TTL_MS configure OAuth2 introspection.

Run

Install dependencies:

npm install

Start stdio MCP server:

npm run start:stdio

Start HTTP MCP server:

npm run start:http

External Services Mode

This project still includes docker-compose.external.yml for app-only runs that point to external services. If you use that mode, configure at least POSTGRES_HOST and VAULT_ADDR in your environment before launching the compose file.

Notes On TeslaMate API Coverage

TeslaMate's native JSON API surface is intentionally small. This MCP includes dedicated tools for all known API-style endpoints and adds teslamate_api_request so new/instance-specific routes can be accessed without waiting for a code change.