tesla-mcp

A private Model Context Protocol server for one Tesla owner, running on Cloudflare Workers. It gives an assistant, or any Streamable HTTP MCP client or script, plain tools for the owner's Tesla vehicles, energy products (Powerwall, solar, Wall Connector), and account: status and data, climate, charging, closures, media, security settings, navigation, and energy settings. The server has no schedules or routines of its own: anything recurring, such as a nightly lock, is run by the caller (see Locking on a schedule).

Vehicle commands are sent as signed Vehicle Command Protocol messages (VCSEC for locks and closures, infotainment for the rest), so they work on vehicles that require Tesla's command signing. The signer is a WebCrypto port checked byte for byte against Tesla's Go implementation: every command payload, both domains' handshakes and signatures, and the encrypted replies. GAP.md maps every Tesla capability to a tool, or says why there is none.

Status: owner-only MVP. One owner, one Tesla account. /mcp accepts the static MCP_BEARER_TOKEN or an access token from the server's own OAuth front door, which the owner approves with a passphrase (see Connecting MCP clients).

Tools

126 tools. 101 are registered by default; the 25 marked dangerous exist only when DANGEROUS_COMMANDS_ENABLED is "true". Every command needs confirm: true and accepts dryRun: true; read tools take neither and never wake the car. Vehicle tools take an optional vehicle_id (the car's id or VIN) and energy tools an optional energy_site_id. Left out, vehicle tools use DEFAULT_VIN if it is set, otherwise the account's only car; energy tools use the account's only site. Each tool's description names the Tesla OAuth scope it needs; see Scopes.

Core

Doors, closures, and alerts

Climate and seats

Charging and schedules

Media and power

Security, access, and settings

Vehicle data, sharing, and Fleet Telemetry

Navigation and sound

Energy (Powerwall, solar, Wall Connector)

Account

Related MCP server: Tessie MCP Server

Safety model

• Confirmation required. Every state-changing tool refuses to act unless called with confirm: true, and accepts dryRun: true to describe the action without contacting the car. Refusals are audited.

• Dangerous commands are off by default. Unlock, remote start, opening the trunk, frunk, tonneau, windows, sunroof, or charge port, turning Sentry Mode off, Valet Mode, PIN to Drive, Speed Limit Mode, Guest Mode, data erase, HomeLink, scheduling a software update, and creating a share invite are only registered when DANGEROUS_COMMANDS_ENABLED is exactly "true" (default "false"). The server checks the same flag again before sending any of them.

• Never wakes implicitly. Reads report "asleep" instead of waking the car, and commands to an asleep car fail with vehicle_asleep. Only tesla_wake and tesla_lock wake it.

• Explicit allowlists. The signer only builds the commands in SIGNED_COMMANDS, and REST calls only go to the endpoints in src/tesla/endpoints.ts, from fixed path templates. It is not a generic proxy.

• Secrets stay secret. Tesla tokens are stored AES-256-GCM encrypted in a Durable Object. Tokens, keys, and raw Tesla responses are never logged or written to the audit log.

• Fail closed. /mcp refuses every request without a valid MCP_BEARER_TOKEN or OAuth access token, and /authorize approves nothing while OAUTH_ADMIN_PASSPHRASE is unset. A command key that does not match the published public key refuses to sign.

Locking

tesla_lock (with confirm: true) is the one lock, for assistants and scripts alike. If the car is asleep or offline it is woken and polled until online (up to about 90 seconds), and the lock is retried, up to 4 attempts within 7 minutes. Failures Tesla marks as not retryable stop at once. If a lock response is lost, the car's lock state is checked instead of sending the lock again. After Tesla accepts the lock, the car's lock state is read back; a car that still reports unlocked gets another attempt. The result says locked, confirmed (the car itself reported locked), woke, and attempts. A failure carries error and a specific reason such as pairing_required, wake_timeout, still_unlocked, or reauth_required.

Locking on a schedule

The server runs nothing on its own. To lock the car every night (or on any other schedule), let your own scheduler (cron, a systemd timer, an assistant's routine, a CI job) call the MCP tools at https://<your-domain>/mcp with Authorization: Bearer <MCP_BEARER_TOKEN> (or an access token for a static client created for the job):

1. Optionally call tesla_auth_status. If authState is reauth_required, alert the owner to sign in again (below) instead of trying to lock.

2. Call tesla_lock with {"confirm": true} (and vehicle_id if the account has more than one car and DEFAULT_VIN is not set). Allow the call up to about 8 minutes: an asleep car is woken and retried within the 7-minute budget.

3. Treat locked: true as success; confirmed: false means Tesla accepted the lock but the car's state could not be read back. On isError, alert on error and reason (for example reauth_required, pairing_required, wake_timeout, still_unlocked). Do not loop on failures: the tool has already retried.

Every call is in the audit log (tesla_audit_recent).

Scopes

Browser sign-in (/login) asks Tesla for all nine scopes the tools use, with prompt_missing_scopes=true so an earlier, narrower grant is widened: openid offline_access vehicle_device_data vehicle_cmds vehicle_location vehicle_charging_cmds user_data energy_device_data energy_cmds. Your developer app must allow each of them (tick them in the developer portal), or Tesla grants fewer. Tesla may also let the owner untick some on its consent page. tesla_auth_status lists the scopes the stored sign-in actually has. openid offline_access vehicle_device_data vehicle_cmds covers every vehicle tool except tesla_vehicle_charging_history and location data. The rest need:

Without them those tools fail with forbidden and name the missing scope. A refresh token from elsewhere (TESLA_BOOTSTRAP_REFRESH_TOKEN) keeps whatever scopes it was issued with. GAP.md has the full mapping.

Self-hosting

You need a Tesla developer account, a Cloudflare account, and a domain you control (Tesla fetches your public key from it). Node 22 or newer.

1. Create a Tesla developer application at developer.tesla.com. Set the allowed origin to https://<your-domain> and the redirect URI to https://<your-domain>/callback, the same value OAUTH_REDIRECT_BASE will produce (step 3). Tesla's portal rejects domains that contain "tesla". Tick the scopes listed under Scopes: vehicle information, vehicle location, vehicle commands, vehicle charging management, profile information, energy product information, and energy product commands.

2. Generate a P-256 command key somewhere outside this repository (*.pem and keys/ are gitignored, but keep the private key off disk where you can):

   openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
   openssl ec -in private-key.pem -pubout -out public-key.pem

3. Publish the public key. Put the contents of public-key.pem in TESLA_PUBLIC_KEY_PEM in wrangler.jsonc (newlines as \n). After deploying, it is served at https://<your-domain>/.well-known/appspecific/com.tesla.3p.public-key.pem. If your account is outside North America, change TESLA_FLEET_BASE_URL to your region's Fleet API host. Set OAUTH_REDIRECT_BASE to https://<your-domain>: browser sign-in sends Tesla ${OAUTH_REDIRECT_BASE}/callback. If the account has more than one car, set DEFAULT_VIN to the VIN (or Fleet vehicle id) tools should use when called without vehicle_id; it must be a car on the account. Left empty, the account's only car is used, and an account with several cars needs vehicle_id on every call (the error lists each car's name, id, and VIN).

4. Set secrets (see .dev.vars.example for what each one is):

   npx wrangler secret put MCP_BEARER_TOKEN
   npx wrangler secret put TESLA_CLIENT_ID
   npx wrangler secret put TESLA_CLIENT_SECRET
   openssl pkcs8 -topk8 -nocrypt -in private-key.pem -outform DER | base64 | tr -d '\n' \
     | npx wrangler secret put TESLA_COMMAND_PRIVATE_KEY_PKCS8_B64
   openssl rand -base64 32 | npx wrangler secret put TOKEN_ENCRYPTION_KEY
   npx wrangler secret put TESLA_BOOTSTRAP_REFRESH_TOKEN   # optional, see step 7
   npx wrangler secret put OAUTH_ADMIN_PASSPHRASE          # approves OAuth clients at /authorize

   Choose a long passphrase for OAUTH_ADMIN_PASSPHRASE (for example openssl rand -base64 24) and keep it in a password manager: anyone who knows it can connect an MCP client. Without it, /authorize refuses every request.

   Create the OAuth KV namespace and put the id it prints into kv_namespaces in wrangler.jsonc (replacing REPLACE_WITH_OAUTH_KV_ID):

   npx wrangler kv namespace create OAUTH_KV

5. Deploy with npm ci && npx wrangler deploy, then attach your domain to the Worker (Workers & Pages → your Worker → Domains & Routes → Custom domain). You can smoke-test /healthz on your workers.dev URL first, but Tesla registration needs your own domain.

6. Register as a Tesla partner for your domain (once per region), using a partner token:

   PARTNER_TOKEN=$(curl -s -X POST https://fleet-auth.prd.vn.cloud.tesla.com/oauth2/v3/token \
     -d grant_type=client_credentials -d client_id="$TESLA_CLIENT_ID" -d client_secret="$TESLA_CLIENT_SECRET" \
     -d scope="openid vehicle_device_data vehicle_cmds" \
     -d audience=https://fleet-api.prd.na.vn.cloud.tesla.com | jq -r .access_token)
   curl -s -X POST https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/partner_accounts \
     -H "Authorization: Bearer $PARTNER_TOKEN" -H 'Content-Type: application/json' \
     -d '{"domain":"<your-domain>"}'

7. Sign in with Tesla. Open https://<your-domain>/login in a browser, sign in to Tesla, and approve the scopes. Tesla sends you back to /callback, which exchanges the code, stores the tokens encrypted (replacing any stored ones), and shows Tesla sign-in updated, scopes: ... with the scopes Tesla granted. The link from /login works once, for ten minutes. The redirect URI sent to Tesla is ${OAUTH_REDIRECT_BASE}/callback, from the non-secret OAUTH_REDIRECT_BASE var in wrangler.jsonc (an https URL; a trailing slash is dropped). It is never taken from the request host, and it must match a redirect URI in the developer app exactly. Tesla rotates refresh tokens and the Worker keeps the newest, so do not share this sign-in with another Tesla tool: whichever one refreshes second is locked out.

   /login is public, so the server remembers which Tesla account its tokens belong to (the access token's sub), and /callback refuses any other account and changes nothing. A TESLA_BOOTSTRAP_REFRESH_TOKEN not used yet is tried before the code, so it names the account first. On a server that has never held a token, the first sign-in names the account: sign in right after the first deploy (or set the bootstrap token). To move the server to another account, set a refresh token for it with TESLA_BOOTSTRAP_REFRESH_TOKEN (below).

   Instead of the browser, you can complete Tesla's authorization-code flow elsewhere and store the refresh token with npx wrangler secret put TESLA_BOOTSTRAP_REFRESH_TOKEN. It seeds the encrypted token store once per distinct value; a browser sign-in supersedes the value set at the time.

   Moving sign-in to another domain. Set OAUTH_REDIRECT_BASE in wrangler.jsonc to the new https://<base> and deploy, register https://<base>/callback as a redirect URI (and the origin as an allowed origin) in the developer app at developer.tesla.com, and route the domain to the Worker (Domains & Routes → Custom domain). A /login link opened before the change no longer completes; start again at /login. If the var is missing or not an https URL, /login and /callback show a configuration error and change nothing.

   Signing in again (reauth_required). If Tesla rejects the stored sign-in (a revoked or expired refresh token), every tool fails with reauth_required, a code-only error is logged, and no further refreshes are tried. Open https://<your-domain>/login again. Alternatively, run npx wrangler secret put TESLA_BOOTSTRAP_REFRESH_TOKEN with a new refresh token: any value that has not been seeded before replaces the stored tokens on the next request; setting the same value again does nothing.

8. Pair the virtual key with the car. On the phone with the Tesla app, open https://tesla.com/_ak/<your-domain> and approve the key. Signed commands fail with "pairing required" until this is done.

9. Connect your MCP client to https://<your-domain>/mcp: see Connecting MCP clients.

Connecting MCP clients

/mcp accepts either credential in Authorization: Bearer ...:

• the static MCP_BEARER_TOKEN, exactly as before (compared in constant time), for scripts and clients that take a fixed header; or

• an access token from the server's OAuth 2.1 front door, for clients such as Claude's custom connectors that sign in with OAuth.

A request without a valid one gets 401 with WWW-Authenticate: Bearer realm="tesla-mcp", resource_metadata="https://<host>/.well-known/oauth-protected-resource/mcp", ..., where MCP clients start OAuth discovery. The host is the one the request was sent to.

OAuth endpoints

Access tokens last an hour and refresh tokens 30 days. Tokens, codes, and client secrets are stored in the OAUTH_KV namespace only as hashes (by @cloudflare/workers-oauth-provider). /mcp, /token, /register, and /.well-known/* answer CORS preflights before any authentication, allow the Authorization, Content-Type, Mcp-Session-Id, and Mcp-Protocol-Version headers, and expose WWW-Authenticate.

The approval page is gated by the OAUTH_ADMIN_PASSPHRASE secret. Each page carries a one-time approval token bound to that exact request (10 minutes, single use), so a form cannot be replayed or posted from elsewhere. After 5 wrong passphrases from one IP, that IP is refused for 15 minutes. Only approve a connection you just started.

Claude (custom connector)

In Claude, add a custom connector with the URL https://tesla-mcp.sean-1b3.workers.dev/mcp (or https://<your-domain>/mcp for your own deployment). Then either:

• Dynamic registration: leave the OAuth client ID and secret empty. Claude registers itself at /register, opens /authorize, and you type OAUTH_ADMIN_PASSPHRASE to approve; or

• Static client: create one (below) with the default redirect URIs, and paste its client_id and client_secret into the connector's advanced settings. You still approve once at /authorize.

Static clients (one per agent)

Give each agent or script its own client, so it can be revoked on its own. Create one (the secret is shown once, and stored only as a hash):

curl -s -X POST https://<your-domain>/admin/clients \
  -H "Authorization: Bearer $MCP_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "nightly-lock agent", "redirect_uris": ["http://localhost:8976/callback"]}'
# {"client_id":"...","client_secret":"...","redirect_uris":[...],...}

redirect_uris is optional and defaults to Claude's two callbacks. The client authenticates at /token with client_secret_basic or client_secret_post, and still uses PKCE. List clients (ids, names, redirect URIs; never secrets), including dynamically registered ones:

curl -s https://<your-domain>/admin/clients -H "Authorization: Bearer $MCP_BEARER_TOKEN"

Revoke a client: it can no longer sign in or refresh, and every access and refresh token it holds is rejected at once.

curl -s -X DELETE https://<your-domain>/admin/clients/<client_id> -H "Authorization: Bearer $MCP_BEARER_TOKEN"

Redirect URI allowlist

Registration (/register and /admin/clients) and every /authorize request accept only:

• https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback;

• http://localhost:<any port>/<any path> and http://127.0.0.1:<any port>/<any path>, for local MCP clients;

• any URI listed, comma separated and matched exactly, in the OAUTH_EXTRA_REDIRECT_URIS var in wrangler.jsonc.

Removing a URI from OAUTH_EXTRA_REDIRECT_URIS stops /authorize from using it for clients registered earlier too.

Development

npm ci
npm run check       # typecheck, Biome lint, tests
npm run deploy:dry  # bundle without deploying

Tests run in the Workers runtime against a simulated Tesla (Fleet API, OAuth, energy sites, and a vehicle that runs real VCSEC and infotainment sessions: ECDH handshakes, signature checks, and encrypted replies). All test credentials are generated at runtime. The Python cross-check of the VCSEC lock in test/vcp-vectors.test.ts comes from scripts/vcsec_vectors.py.

bash conformance/run.sh (needs Go and git) checks the shared vectors against Tesla's official Go implementation at a pinned commit of teslamotors/vehicle-command:

• test/vectors/vcsec-lock.json and test/vectors/infotainment-honk.json: key derivation, the handshake, signing, the response request hash, and AES-GCM reply decryption, in both domains, through Tesla's Signer and Verifier.

• test/vectors/vcp-commands.json: the payload of every signed command, byte for byte, as Tesla's own pkg/vehicle methods build it.

CI runs it as the go-conformance job. Without a local Go, docker run --rm -v "$PWD":/repo:ro -w /repo golang:1.27.3 bash conformance/run.sh works too.

License

MIT. See LICENSE.