polestar-mcp
You can use this read-only MCP server to ask plain-language questions about a Polestar vehicle's current state and charging setup, and get derived briefings, security/health checks, estimates, and charge plans.
Discover accessible vehicles and supported data domains, and inspect server budget/cache/token status.
Read telemetry domains: availability, battery/charge, exterior/locks, health/service warnings, location, odometer/trips, parking climatization, and cabin pre-cleaning.
Read charging settings and state: amp limit, charge locations, charge-now, charge timers, target SoC, and at-charge-location status.
Get aggregate answers: full car status briefing, secure/not-secure verdict, active warnings, charging time/energy estimate, and cheapest charging schedule from your spot prices.
With history enabled, analyze past battery degradation, charging sessions/costs, warning changes, service forecasts, settings changes, trips, timelines, and weekly digests.
Cannot control the car: no locking, climate start, charge-limit changes, or other writes; API access is read-only except the OAuth token request.
Provides read-only access to the Polestar Data Portal M2M API for connected Polestar vehicles, including vehicle status, battery and charging information, location, health warnings, and charging estimates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@polestar-mcp How is my car doing?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
polestar-mcp
Read-only MCP server for the Polestar Data Portal machine-to-machine (M2M) API. Ask about your car in plain language and get answers from what the car reports.
A Model Context Protocol server for the Polestar Data Portal, for clients such as Claude Desktop or Cursor, or your own.
polestar-mcp is a personal project for one owner's Polestar 2. It is not affiliated with or endorsed by Polestar. The package is not published to npm or the MCP Registry yet, so run it from a clone.
What it does
The server connects an MCP client to the Polestar Data Portal. Ask "how is my car doing?" and the assistant calls one tool and returns a short briefing: charge, range, locks, availability, odometer, service countdown, and how old each value is. Charging questions work the same way, from a time-to-target estimate to a cheapest-hours plan built from spot prices you supply.
The API is read-only, and so is this server. Every network call a tool makes is a GET; the only POST is the OAuth token request. Polestar's documented v1 API publishes no write endpoints, so nothing here can lock the car, start the climate, or change a charge limit. Every tool declares readOnlyHint and idempotentHint, and tools that reach the API also set openWorldHint. Clients that honour those hints may run reads without asking; clients that ignore them still show a confirmation.
A default start exposes 26 tools. Setting POLESTAR_HISTORY_DIR adds ten history tools and raises the surface to 36. The extra tools answer questions the API cannot, such as how the battery has aged, what a charging session cost, and what changed this week.
A question follows one path:
sequenceDiagram
participant You
participant Client as MCP client
participant Server as polestar-mcp
participant Cache as cache
participant API as Polestar API
You->>Client: How is my car doing?
Client->>Server: tools/call get_car_status
Server->>Cache: battery, exterior, availability, odometer, health, target
alt fresh entries
Cache-->>Server: last values, each with an age
else stale or missing
Cache->>API: GET the missing domains
API-->>Cache: payloads
Cache-->>Server: values with ages
end
Server-->>Client: one briefing
Client-->>You: charge, range, locks, agesRelated MCP server: Unoffical Polestar 2 MCP
Contents
Requirements
Node.js 20.11 or newer, with git and npm.
An MCP client that can launch a local process over stdio, the transport a client uses to start a server as a child process.
A Polestar Data Portal credential for live mode: client ID, client secret, and Account ID. The sample-data path needs none of them.
macOS, Linux, or Windows. The credential recipe below is POSIX shell; on Windows, create the same file with an editor.
A clone of this repository. The package is not on npm yet, so
npm cioutside a clone will fail.
Quick start
Get the code
git clone https://github.com/nicolaskheirallah/polestar-mcp.git
cd polestar-mcp
npm ci
npm run buildnpm ci installs the locked dependencies and npm run build writes build/server.js, the file an MCP client launches. npm start runs the same file directly.
Try it with sample data
The repository ships a sanitized capture of API responses under test/fixtures/dump. Fixture mode replays that capture through the full server, including the token flow, and never reads a secrets file or contacts Polestar.
npm run demoThe demo prints DUMP_OK when every assertion passes. To ask questions against the sample data, register the server in your client with the fixture directory. This is the same mcpServers block as the live setup below, with one extra env entry:
{
"mcpServers": {
"polestar-sample": {
"command": "node",
"args": ["/absolute/path/to/polestar-mcp/build/server.js"],
"env": {
"POLESTAR_FIXTURES_DIR": "/absolute/path/to/polestar-mcp/test/fixtures/dump"
}
}
}
}Restart the client and ask "how is my car doing?". npm start on its own starts a stdio server that waits for a client, so it is not a web page; the client configuration is what connects them. Fixture mode runs the real authentication lifecycle, so a capture without a token response fails with AuthError: Token request failed (HTTP 404) rather than skipping auth. A route with no fixture answers NOT_FOUND, which is deliberately different from DATA_NOT_AVAILABLE: a missing fixture cannot pass as a car that reports nothing.
Connect your car
Log in at data-portal.polestar.com, open the Data Portal API tab, and create a credential. The portal gives you three values: the OAuth client ID, the client secret (shown once), and the Account ID (
x-client-id). The Account ID is not the client ID. The client ID authenticates the token request; the Account ID identifies you on every vehicle request. Using the client ID as the Account ID makes every call fail with403 AUTHZ_CLIENT_ID_MISMATCH, and the server warns at startup when the two match.Store the values outside any repository:
mkdir -p ~/.config/polestar-mcp cat > ~/.config/polestar-mcp/.env.secrets <<'EOF' POLESTAR_CLIENT_ID=paste-your-client-id-here POLESTAR_CLIENT_SECRET=paste-your-client-secret-here POLESTAR_ACCOUNT_ID=paste-your-account-id-here EOFOn Windows, create
%USERPROFILE%\.config\polestar-mcp\.env.secretsin an editor with the same three lines..env.examplelists every variable as a template.Register the server in your MCP client:
{ "mcpServers": { "polestar": { "command": "node", "args": ["/absolute/path/to/polestar-mcp/build/server.js"] } } }Claude Desktop reads
claude_desktop_config.json; other clients expose MCP servers in their settings and many accept the samemcpServersshape. Use the absolute path tobuild/server.js, and the absolute path to your Node executable if the client cannot findnodeon its PATH.Restart the client.
Real environment variables win over the secrets file, so either source works:
{
"mcpServers": {
"polestar": {
"command": "node",
"args": ["/absolute/path/to/polestar-mcp/build/server.js"],
"env": {
"POLESTAR_CLIENT_ID": "<client id>",
"POLESTAR_CLIENT_SECRET": "<client secret>",
"POLESTAR_ACCOUNT_ID": "<account id, not the client id>"
}
}
}
}What the client supports changes the experience:
Client capability | Effect |
Launches a stdio process | The full surface, including resource subscriptions |
Speaks Streamable HTTP | The same tools, resources, and prompts, but no subscriptions |
Supports MCP prompts | Sees |
Honours | May run reads without confirmation; clients that ignore hints still ask |
Supports MCP elicitation or the 2026 input flow | Several cars trigger a "which car" question; without it the call returns |
The server writes diagnostics to stderr; stdout carries the MCP protocol. If the client never shows the server, the reason is in the client's MCP log, not in the chat.
Check it works
Run the two checks that do not need a client or a car:
node build/server.js --version # 0.3.0
npm run demo # DUMP_OKThen ask the client for polestar_status. In live mode it reports the budget used, the cache state, and the token expiry; get_car_status answers with a data age. On startup the server writes a line like live · v0.3.0 · budget 10000/day · cache on · history off and ready: 26 tools over 15 domains to stderr. If nothing works, start with Troubleshooting.
Troubleshooting
What you see | What it means | What to do |
The client shows no polestar server | The client could not start | Run |
| No secrets file and no client | Create the secrets file, or fill the |
|
| Use the Account ID shown next to the Base URL in the Data Portal |
| The client ID or secret is wrong | Re-create the credential and update the secrets file |
| Wrong base URL, or a fixture dump without a token response | Check |
| The 10,000 calls/day ceiling was reached | Wait for the midnight UTC reset, or raise |
| Several cars and no | Call |
| HTTP mode on a non-loopback address without a bearer token | Bind |
A tool answers "No ... data is available" | The car does not report that topic | This is a normal answer, not a failure |
node build/server.js --version and --help exit before the protocol starts and prove the build and Node version. POLESTAR_LOG=debug adds verbose stderr. The full table, including invalid configuration and fixture NOT_FOUND, is in getting started.
What you can ask
You ask | The assistant calls | You get |
"How is my car doing?" |
| A short briefing: charge, range, locks, availability, odometer, service, data ages |
"Is everything locked?" |
| A yes/no verdict that names anything open |
"Does anything need attention?" |
| Active warnings only, plus the service countdown |
"When will it be charged?" |
| Energy and time to target, with assumptions stated |
"Plan the cheapest charging tonight" |
| A schedule of hours from a spot-price curve you supply |
"Where is the car?" |
| Last known position with heading, speed, and data age |
"How has the battery aged?" |
| Capacity and range trends (needs history) |
"What is my charging setup?" |
| The seven charging settings in one answer, each with its age |
"Will the car be ready by Sunday at 14:00?" |
| Yes or no with the charge deadline, or a refusal when the timer cannot support it |
"What did charging cost me?" |
| Energy, cost and assumptions per recorded session (needs history) |
"What did I drive this week?" |
| Trips rebuilt from odometer history, gaps and resets named (needs history) |
"Catch me up on the week" |
| Distance, charge, warnings and settings changes in one answer (needs history) |
Vehicle My Car, telemetry/battery (data observed 12 min ago)
Charge: 52% · range 170 km
Charging: Idle · Unplugged
Average consumption: 20.1 kWh/100kmThe vehicle label comes from POLESTAR_VEHICLE_LABELS; without one the header shows the VIN, masked when POLESTAR_REDACT_VIN=1. The values match the sample data, and the age is illustrative. Domain tools answer in short prose. Passing raw: true appends the untouched API payload. A successful result carries that text plus structured data where the tool has one; failures use structuredContent.message.
Vehicle My Car, telemetry/exterior (data observed 52 d ago)
All doors, windows, hood and tailgate closed · Locked · alarm idleVehicle My Car, telemetry/odometer (data observed 52 d ago)
Odometer: 122,953 km
Trip meters: 2,863 km manual · 136 km automaticVehicle My Car, telemetry/health (data observed 52 d ago)
Service in 313 days / 4150 km
No warningsYes, car is secure (locked, all closed). Alarm: idle.The ages are relative to when the sample data was captured. is_car_secure reads from the cache and answers without its own header.
Example: plan the cheapest charge
The prices are yours; the planner uses the car's charge window, target charge level, and amp limit. Here is the sample car, whose window is 23:00 to 06:00 at UTC+02:00 and whose target is 80 percent:
{
"prices": [
{ "startsAt": "2026-11-09T21:00:00.000Z", "price": 0.42 },
{ "startsAt": "2026-11-09T22:00:00.000Z", "price": 0.35 },
{ "startsAt": "2026-11-09T23:00:00.000Z", "price": 0.31 },
{ "startsAt": "2026-11-10T00:00:00.000Z", "price": 0.28 },
{ "startsAt": "2026-11-10T01:00:00.000Z", "price": 0.26 },
{ "startsAt": "2026-11-10T02:00:00.000Z", "price": 0.24 },
{ "startsAt": "2026-11-10T03:00:00.000Z", "price": 0.22 }
]
}The answer names the hours it picked, the energy in each, and the assumptions it made:
Charge plan (note: the car window is defined but INACTIVE on the car)
Need: 18.399 kWh at the battery (20.444 kWh from the grid at 90% AC efficiency) to go from 52% to 80% in about 1.33h at 13.8 kW
- 2026-11-10T02:00:00.000Z to 2026-11-10T03:00:00.000Z @ 0.24: 13.8 kWh at the battery, 15.3 kWh from the grid
- 2026-11-10T03:00:00.000Z to 2026-11-10T04:00:00.000Z @ 0.22: 4.6 kWh at the battery, 5.1 kWh from the grid
Estimated cost: 4.804 (the caller's currency per kWh)The tool says when it cannot plan. Missing prices for any planned hour are refused rather than counted as zero, and a window that is too short is reported as infeasible with the shortfall.
The tools
One domain is one topic of vehicle data, such as telemetry/battery. The 15 get_* tools in the Telemetry and Charging groups map one-to-one onto the API's 15 read domains: 8 telemetry, 7 charging. The aggregate, planning, system, and history tools build on those reads or answer from local state.
Every tool that reads a car takes an optional vin, the vehicle identification number. Omit it when the credential sees one vehicle. With several, the server asks the client which car when the client supports MCP elicitation or the 2026 input flow, validates the answer, and otherwise refuses with AMBIGUOUS_VIN and the known VINs so you can pass one explicitly. Argument names are strict; a misspelled vin is refused by name instead of quietly reading the default car. Third-party credentials can pass delegated_account_id, which is checked against the operator's allowlist because the API accepts unknown delegated IDs without complaint.
A default start exposes 26 tools: 15 domain tools, 7 aggregate and planning tools, list_vehicles, list_domains, list_vehicle_domains, and polestar_status. With POLESTAR_HISTORY_DIR set, ten history tools join and the surface is 36.
flowchart TB
Client[MCP client] --> Server[polestar-mcp]
Server --> Domains[15 domain tools<br/>8 telemetry, 7 charging]
Server --> Aggregates[7 aggregate and planning tools]
Server --> Listings[3 listing tools]
Server --> Status[polestar_status]
Server --> History[10 history tools<br/>needs POLESTAR_HISTORY_DIR]
Domains --> API[Polestar Data Portal API]
Aggregates --> API
Listings -.-> API
History --> Store[(local JSONL store)]Tool | What it answers |
Discovery | |
| VINs, or your friendly names, that this credential may access |
| The server's own registry: every domain with endpoint, scope, and tool name |
| Which of the 15 domains this car reports, which are absent or refused, with data ages |
Telemetry | |
| Whether the car is reachable or awake, and its usage mode |
| Charge level, charging status and power, range, time to full, consumption, usable energy |
| Doors, windows, hood, tailgate, tank lid, central lock, tailgate lock, alarm |
| Service countdown (days, distance, engine hours) and fluid, light, and 12V warnings |
| Last known position, heading, speed, timestamp |
| Odometer and trip meters, average speeds |
| Preheat or pre-cool status, runtime left, requested seat and wheel heating |
| Cabin air: PM2.5, air quality index, last pre-cleaning cycle |
Charging | |
| Configured maximum AC charging current, source, last update |
| Charge-location settings, often without addresses |
| Charge-now override state and timer sync |
| Recurring charge window: hours, timezone offset, activation, sync |
| Scheduled climate timers: ready-at hour, weekdays, activation |
| Target charge level and setting type |
| Whether the car is at a saved charge location, often unreported |
Aggregates and planning | |
| The briefing in one call: several domains at once, each value aged |
| Yes/no security verdict that names anything open |
| Active warnings only |
| Energy and time to target, assumptions shown |
| All seven settings at once, each aged |
| Cheapest hours inside the car's charge window, given your spot prices |
| Whether the car can be charged and preconditioned by a departure time |
System | |
| Budget used and remaining with reset time, cache hit rate, token expiry, mode |
History (opt-in) | |
| Recorded samples for one domain, one line per change |
| Implied full-charge range and capacity trend over history, with a 95% interval once the span allows it |
| Charging sessions reconstructed from battery samples |
| Energy and cost of each recorded session, assumptions and missing prices named |
| Warnings that appeared or cleared between recorded health samples |
| Which service limit arrives first, from the car's countdown and your odometer rate |
| Recorded changes to charging settings, dated by the value clock |
| Trips reconstructed from odometer history, gaps and resets named |
| Cross-domain timeline of what changed, over a window of hours |
| One seven-day digest: distance, charge, warnings, settings |
list_domains prints the endpoint and OAuth scope for every domain; docs/tools-reference.md has the full mapping, scopes, and worked examples.
History and privacy
The API reports current state only, so questions about the past need a local store. Set POLESTAR_HISTORY_DIR and the server appends each live domain answer to a JSONL file, one JSON object per line, under that directory. The layout is one subdirectory per vehicle, named by VIN, and one <kind>-<domain>.jsonl file per domain. Deduplication is by the cloud's change ID (metaEventId): an unchanged snapshot is not appended, so a file grows only when the car reports a change. When a file would pass 64 MiB, it is rewritten with its newest half, so an unattended install does not grow without bound. Position is recorded only when location reads are allowed, and deleting the directory removes the history. Recording is passive: it reuses answers the server already fetched. To sample while nobody is asking, set POLESTAR_SAMPLE=1; the sampler covers battery, odometer, location, and exterior every 10 minutes by default and pauses at 80 percent of the budget. It requires POLESTAR_HISTORY_DIR.
flowchart LR
Read[tool call reads a domain] --> Store[(JSONL store)]
Sample[background sampler<br/>POLESTAR_SAMPLE=1] --> Store
Store --> Tools[10 history tools]
Tools --> Answers[degradation, sessions, cost, trips, timeline, digest]Credentials stay on the machine, requests go only to Polestar, and the server sends no telemetry. The history store is opt-in. The full policy is in docs/privacy.md.
These variables control what leaves the car and how answers label it:
Variable | Effect |
|
|
| Masks VINs in tool text, the structured envelope, resource names, descriptions and bodies, completions, prompt text, and error text. Three documented exceptions: |
|
|
Resource URIs are the one client-visible surface redaction does not cover. If a transcript must not carry the VIN, do not enable resource listing for that client. History files are created 0600 and per-vehicle directories 0700.
Configuration
All configuration is environment-only. Most installs set only the three credentials; everything else has a default. .env.example lists every name as a template. The server warns about unrecognized variables and suggests the closest real name; with POLESTAR_STRICT_ENV=1 a typo is fatal. A value that is present but unusable, such as a bad URL, a non-numeric timeout, or an out-of-range port, fails fast with the fix in the message.
Variable | Default | Purpose |
| required live | OAuth client ID from the Data Portal |
| required live | OAuth client secret |
| required live | The Account ID, sent as |
| unset | Default delegated account for third-party credentials |
| unset | Allowlist a call's |
| production URL | Override the API base URL |
|
| Override just the token endpoint |
| unset | Serve captured responses instead of the live API |
| unset | Alternative dotenv path (default |
| 15000 | Hard deadline per HTTP request |
| 10000 | Daily live-call ceiling; fails closed at the limit |
| 100 | Rolling per-minute ceiling; waited out rather than failed when the wait fits the deadline |
| unset | Absolute path to a JSON file that keeps the daily call count across restarts and processes |
| on |
|
| all domain scopes | Space- or comma-separated scope override for the token request |
| unset | Enable the JSONL history store and the history tools here |
| 600 | Seconds between sampler rounds (clamped 60 to 3600) |
| off |
|
| unset |
|
| off |
|
| on |
|
| km |
|
| normal |
|
| off | Scaffold for future write endpoints; registers nothing today |
| 0 (stdio) | 1 to 65535 switches to Streamable HTTP |
| 127.0.0.1 | HTTP bind address |
| unset | Bearer token for HTTP mode; required off loopback and at least 16 characters |
| unset | Comma-separated absolute origins a browser client may call from; when set, the list replaces the default same-origin rule |
| off |
|
Rate limits, caching, and tokens
Polestar's M2M credential allows 10,000 calls per client per rolling UTC day and 100 per minute. The daily window resets at midnight UTC, and polestar_status reports resetsAtUtc. The token request and every retry attempt are metered against the same allowance, while cache hits and fixture reads are not.
A request travels client, tool, Polestar client, cache, retry, budget meter, API. The path is also drawn below; the sentence above is the fallback when the diagram does not render.
flowchart LR
C["MCP client<br/>stdio or HTTP"] --> T["26 or 36 read tools<br/>plain-language answer"]
T --> K["PolestarClient<br/>VIN resolution<br/>identity checks"]
K --> H["Cache<br/>per-domain TTLs<br/>stale-while-revalidate"]
H --> R["Retry<br/>429 / 5xx<br/>Retry-After"]
R --> B["Budget meter<br/>10,000 per day<br/>fails closed"]
B --> P["Polestar M2M API"]
H --> S["History store<br/>opt-in JSONL"]The cache lifetime (TTL) depends on how fast the value changes:
Data | Cache lifetime |
Battery, location, exterior | 30 seconds |
Availability, odometer, parking climatization | 60 seconds |
Charging settings: amp limit, target charge, timers, charge now, charge locations | 5 minutes |
Health | 10 minutes |
Pre-cleaning | 30 minutes |
Vehicle list | 1 hour |
When an entry expires, the last value is served immediately, marked stale, while one shared refresh runs in the background.
Retries cover 429 responses (honouring Retry-After), 500, 502, 503, and 504, up to three attempts with capped backoff. A GET that fails on a network error gets one extra attempt. Every attempt is metered before it leaves.
The budget fails closed. When the daily allowance is gone, further calls are refused with the reset time instead of spending calls beyond the limit. The counter lives in memory by default; POLESTAR_BUDGET_LEDGER points it at a JSON file shared across restarts and processes. polestar_status reports budget, cache, and token state. The resource poller and sampler pause automatically at 90 percent and 80 percent of the budget so background work cannot consume the quota you need.
Tokens are cached. One token request covers the union of all domain scopes (trim it with POLESTAR_SCOPES for least privilege), and the token is reused until expiry minus a five-minute skew. Concurrent callers share one request, and a 401 triggers exactly one fresh-token retry.
stateDiagram-v2
[*] --> NoToken
NoToken --> Trusted: POST /token
Trusted --> Trusted: calls reuse the cached token
Trusted --> Refreshing: next call inside five minutes of expiry
Trusted --> Refreshing: API answers 401, one retry
Refreshing --> Trusted: new token
Refreshing --> Error: token request fails
Error --> [*]Resources, prompts, and subscriptions
The server exposes resources at polestar://vehicle/{vin}/{telemetry|charging}/{domain}. The list comes from the vehicles your credential can see, and the VIN and domain arguments support completions. Reading a resource returns the same plain-language view as the matching tool, and two resource templates are registered, one per kind.
Subscriptions need a client that supports resources.subscribe and a stdio session. The server re-reads a subscribed resource once a minute through the cache and notifies the client only when the cloud's metaEventId changes, which happens when the car reports something new. A session holds at most 50 subscriptions, and the poller pauses while 90 percent of the daily budget is spent. Over HTTP, resources/subscribe returns -32601 and the handshake advertises subscribe: false instead of accepting a subscription that can never fire.
The server ships two prompts, car-status and charge-plan; battery-health-report joins when the history store is enabled. Each wires a common question to the right tool sequence. Nothing mutates, so clients that honour readOnlyHint may run these reads without asking.
Run it over HTTP
Set a port and a token to serve the same engine over stateless Streamable HTTP:
POLESTAR_HTTP_PORT=8420 POLESTAR_HTTP_TOKEN=<at-least-16-characters> npm startEach request is independent, while cache, budget, and history are shared. The listener binds 127.0.0.1 by default and prints its URL on stderr. A non-loopback bind requires POLESTAR_HTTP_TOKEN of at least 16 characters and is refused at startup otherwise. The listener speaks plain HTTP with no TLS of its own, so keep it on loopback or put it behind a proxy that terminates TLS and authenticates callers. The token is a shared secret, not per-user authentication: anyone who holds it can read every vehicle the credential can see.
Point an HTTP-capable client at http://127.0.0.1:8420/mcp and send Authorization: Bearer <token>; the root URL answers too. Browser cross-origin requests are refused unless the Origin matches the request host or appears in POLESTAR_HTTP_ALLOWED_ORIGINS. When that allowlist is unset, the request's own host is the default; when it is set, the list replaces that default. A forged Host is refused either way.
Both protocol eras are served from one listener. A 2025-era client gets the stateless legacy path; a 2026-07-28 client gets server/discover plus the per-request envelope, with the same 26-tool default surface, or 36 with history enabled. A modern request missing its envelope is refused by name, never silently downgraded. Resources and prompts work in both modes; subscriptions remain stdio only.
An initialize request:
curl -s http://127.0.0.1:8420/mcp \
-H 'Authorization: Bearer <token>' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'The reply arrives as a server-sent event; the JSON-RPC message is on the data: line, abbreviated here:
event: message
data: {"result":{"protocolVersion":"2025-06-18","capabilities":{"resources":{"subscribe":false},"tools":{},"prompts":{}},"serverInfo":{"name":"polestar-mcp","version":"0.3.0"}},"jsonrpc":"2.0","id":1}A tool call uses the same shape with "method":"tools/call" and "params":{"name":"get_battery","arguments":{}}. The listener is stateless per request; the cache, budget, and history are shared across requests.
Development and testing
npm ci
npm run build
npm run typecheck # types src, test, and scripts together
npm test # unit and integration suites
npm run coverage # the same suite with the lines 90, branches 80, functions 85 floors
npm run demo # offline demo against the shipped synthetic dump, prints DUMP_OKThe full check set, including smoke, smoke-http, smoke-bin, demo-dump, verify-fixtures, the secret and version gates, and the documentation gates, is in CONTRIBUTING.md. CI runs it on every push and pull request, on Node 20.11, 22, and 24.
The suite covers the cases that are easy to get wrong here. Token single-flight, cache TTLs, envelope unwrapping, VIN resolution, retry and budget metering, and the configuration registry each have direct tests. So do the harder edges: expiry skew, identity checks, delegation, stale-while-revalidate, the charge-window planner including windows that wrap midnight, and history deduplication with session reconstruction.
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md before opening one: every behaviour claim needs a check, writing hygiene is enforced tree-wide, and a live capture must never be committed. Run npm test and node docs/check-docs.mjs hygiene before pushing.
Security
The threat model is in SECURITY.md. Credentials live outside the repository, at ~/.config/polestar-mcp/.env.secrets or a path set with POLESTAR_ENV_FILE, and no .env-family file inside the tree is acceptable. npm run check-secrets scans the repository for JWTs, opaque credential blobs, VIN-shaped identifiers including ones embedded in longer tokens, personal email, phone numbers, and precise coordinates; it skips dependency and build directories and binary or image files. Each detector proves itself on a positive control before a clean scan counts.
Captured dumps are credentials. They contain long-lived refresh tokens and location history. Do not commit them, paste them into issues, or share them casually.
Failures carry the upstream code, httpStatus, and, when Polestar sent one, the requestId that support can look up. Quote the requestId in a report and do not paste the request body.
Documentation
For users:
Document | Contents |
Credentials, every variable explained, first calls, troubleshooting | |
All 36 tools, with endpoints and scopes for the route-bound ones, and example responses | |
What is processed, where it goes, what stays local, and the owner's controls |
For developers and reviewers:
Document | Contents |
The client module, the cache/retry/budget chain, history, resources, HTTP mode | |
Authentication, headers, envelope, errors, rate limits | |
What live probes settled about identity headers, VINs, domains, errors, and the token endpoint | |
The test map, the CI checks, adding a tool | |
Why the consumer app API stays unwired, and the shape when it lands | |
The designed but dormant write surface and its safety rules | |
Sample data, the example prompts, the directory checklist and the distribution status | |
The |
Project status
The documented v1 API is read-only and this server is read-only with it. Polestar publishes no v1 write endpoints, so POLESTAR_ENABLE_WRITES registers nothing. The app-side consumer API, which would add car model details and render images, is deliberately not wired in: its GraphQL queries are unpublished and its refresh tokens rotate destructively, so depending on it would mean depending on a contract that can be revoked without notice.
Out of scope, deliberately:
write or control endpoints of any kind
a hosted service, backend, or project database
user accounts or per-user authentication for HTTP mode
a web or mobile interface
webhooks or push notifications
price fetching; prices are an argument to
plan_cheapest_chargenotifications over HTTP
The npm package and MCP Registry entry are prepared in this tree, and the release workflow checks, packs, and publishes on a version tag, but neither is published yet. Publishing is blocked on the owner's npm credentials and on npm name availability. The Claude Desktop .mcpb metadata exists in mcpb/manifest.json; building the bundle is blocked on the mcpb CLI and a desktop host to test it. Until those land, run the server from a clone with npm ci && npm run build.
polestar-mcp is a personal project for one owner's Polestar 2. It is not affiliated with or endorsed by Polestar.
License
MIT. See LICENSE.
Available Tools
23 toolsget_amp_limitGet amp-limitARead-only
Configured maximum AC charging current (amps) with its source and last update, plus pendingAmpLimit when a change is recorded but the car has not confirmed it. Measured live. (M2M endpoint: /v1/vehicles/{vin}/charging/amp-limit, scope pdp-charging/ampLimit).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_availabilityGet availabilityARead-only
Vehicle availability: availabilityStatus and usageMode (whether the car is currently reachable/awake). (M2M endpoint: /v1/vehicles/{vin}/telemetry/availability, scope pdp-telemetry/availability).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_batteryGet batteryARead-only
Battery state: charge level %, charging status (V1/V2/type), charger connection and power status, estimated distance to empty (km and miles), estimated time to full, and average consumption kWh/100km. The contract also defines charging current and voltage, charging power, since-charge and automatic-trip consumption averages, and an energy-consumption breakdown: those appear only when the car reports them, so a missing field means unreported, not zero. The reference vehicle answered with 14 fields and none of the optional ones. (M2M endpoint: /v1/vehicles/{vin}/telemetry/battery, scope pdp-telemetry/battery).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_car_statusGet full car statusARead-only
One-call status of the car: charge level and state, range, lock/doors, availability, odometer, service countdown, and data age for each. Costs several domain reads (cached); use instead of calling five get_* tools.
Inputs: vin. Returns: ok, vin, code, data, +6 more
get_charge_locationsGet charge-locationsARead-only
Configured charge locations. Over M2M this answers as a settings record — typically only an id and a utc0 flag, not a list of addresses — so finding no coordinates is normal rather than a failure. (M2M endpoint: /v1/vehicles/{vin}/charging/charge-locations, scope pdp-charging/chargeLocations).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_charge_nowGet charge-nowARead-only
Charge-now override state. Over M2M it typically carries only the last sync timestamp of the override, not an active/inactive boolean. (M2M endpoint: /v1/vehicles/{vin}/charging/charge-now, scope pdp-charging/overrideChargeTimer).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_charging_estimateCharging time and energy estimateARead-only
Estimates the energy and time needed to reach the target charge level from the current SoC, using the reported usable energy (dischargeInfo.energyAvailable) when available, the configured amp limit for power, and the car's own time-to-full when charging.
Inputs: vin, phases. Returns: ok, vin, code, data, +6 more
get_exteriorGet exteriorBRead-only
Exterior state: doors, windows, hood, tailgate, tank lid (open/closed), central lock, tailgate lock, alarm. (M2M endpoint: /v1/vehicles/{vin}/telemetry/exterior, scope pdp-telemetry/exterior).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_global_charge_timerGet global-charge-timerARead-only
Recurring charge window: start/stop hour with timezone offset, activation flag and sync status. Pending changes appear only when an edit has not yet reached the car; an empty pending block means nothing is queued. (M2M endpoint: /v1/vehicles/{vin}/charging/global-charge-timer, scope pdp-charging/globalChargeTimer).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_healthGet healthARead-only
Service health: days/distance/engine-hours to service, service warning, and fluid/light/12V warnings (brake fluid, coolant, oil, washer fluid, 19 exterior light positions). (M2M endpoint: /v1/vehicles/{vin}/telemetry/health, scope pdp-telemetry/health).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_is_at_charge_locationGet is-at-charge-locationARead-only
Whether the vehicle is currently at a saved charge location. Often unsupported on a vehicle (returns DATA_NOT_AVAILABLE). (M2M endpoint: /v1/vehicles/{vin}/charging/is-at-charge-location, scope pdp-charging/isAtChargeLocation).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_locationGet locationARead-only
Last known position: latitude, longitude, altitude, heading, speed, with timestamp. (M2M endpoint: /v1/vehicles/{vin}/telemetry/location, scope pdp-telemetry/location).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_needs_attentionHealth warnings needing attentionARead-only
Only the active warnings from the health domain (fluids, lights, 12V, service) plus the service countdown. Empty means nothing needs attention.
Inputs: vin. Returns: ok, vin, code, data, +6 more
get_odometerGet odometerBRead-only
Odometer meters, trip meters (manual and automatic, km), average speeds (km/h). (M2M endpoint: /v1/vehicles/{vin}/telemetry/odometer, scope pdp-telemetry/odometer).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_parking_climate_timerGet parking-climate-timerARead-only
Scheduled parking-climate timers: ready-at hour, weekdays, repeat flag, activation. (M2M endpoint: /v1/vehicles/{vin}/charging/parking-climate-timer, scope pdp-charging/parkingClimateTimer).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_parking_climatizationGet parking-climatizationARead-only
Parking climate (preheat/pre-cool): running status, runtime left, requested seat and steering-wheel heating intensities, ventilation. (M2M endpoint: /v1/vehicles/{vin}/telemetry/parking-climatization, scope pdp-telemetry/parkingClimatization).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_pre_cleaningGet pre-cleaningARead-only
Cabin air pre-cleaning: running status, measured PM2.5 / air quality index, last cycle validity and completion time. (M2M endpoint: /v1/vehicles/{vin}/telemetry/pre-cleaning, scope pdp-telemetry/preCleaning).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
get_target_socGet target-socARead-only
Target battery state of charge (%), setting type (CUSTOM/PRESET), last update. (M2M endpoint: /v1/vehicles/{vin}/charging/target-soc, scope pdp-charging/targetSoc).
Inputs: raw, vin, delegated_account_id. Returns: ok, vin, code, data, +6 more
is_car_secureIs the car closed and lockedARead-only
True/false security check: are all doors, windows, hood and tailgate closed, central lock engaged, alarm OK? Names anything open.
Inputs: vin. Returns: ok, vin, code, data, +6 more
list_domainsList data domainsARead-only
Every domain this server reads, with its endpoint, OAuth scope and tool name. Answer from here rather than guessing a domain name: an unknown domain is a 404 VALIDATION_RESOURCE_NOT_FOUND from the API, which is a different thing from a vehicle reporting no data.
Inputs: no named parameters. Returns: ok, vin, code, data, +6 more
list_vehiclesList vehiclesARead-only
List the VINs this Polestar Data Portal credential is authorized to access.
Inputs: no named parameters. Returns: ok, vin, code, data, +6 more
plan_cheapest_chargePlan the cheapest chargeARead-only
Given hourly electricity prices, computes the cheapest hours inside the car's charge window (from global-charge-timer) that deliver enough energy to reach the target charge level.
Inputs: prices (required), vin, phases, capacityKwh. Returns: ok, vin, code, data, +6 more
polestar_statusServer statusARead-only
Server self-report: daily API budget (used/limit/reset), per-minute ceiling, cache hit rate, token expiry, and mode. Call this if you suspect you are burning through the daily API budget.
Inputs: no named parameters. Returns: ok, vin, code, data, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools map cleanly to distinct M2M resources, so get_location, get_odometer, and get_exterior are unambiguous. The main overlap is get_health versus get_needs_attention, and get_car_status intentionally aggregates several get_* tools, which creates mild selection ambiguity.
The dominant pattern is snake_case get_<resource>, which is predictable and consistent across the telemetry and charging tools. The pattern is not perfectly uniform because of list_vehicles, list_domains, is_car_secure, plan_cheapest_charge, and polestar_status.
23 tools sits in the 16-25 range that feels heavy for an agent to navigate. Each tool is mostly endpoint-aligned, but the aggregate and derived helpers such as get_car_status, is_car_secure, get_needs_attention, and plan_cheapest_charge add useful value while also pushing the set toward redundancy.
The read-side surface is broad, covering the major telemetry domains, charging settings, and helpful derived queries, with list_domains preventing endpoint guessing. The main gaps are the lack of any write/control operations and some niche vehicle telemetry such as software version or tire pressure, which agents could work around.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides access to Tesla vehicle telemetry data via the Tessie API, enabling real-time monitoring of battery status, charging state, climate controls, location, and other vehicle metrics through 30+ tools with intelligent caching.-
- AlicenseNot gradedqualityDmaintenanceAn MCP (Model Context Protocol) server that exposes Polestar 2 vehicle data to AI assistants like Claude. Query your car's battery status, vehicle info, and health data through natural conversation.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for controlling Polestar vehicles via natural language, enabling climate, charging, locks, location, and vehicle status management through Claude.MIT
- AlicenseCqualityCmaintenanceEnables reading Tesla vehicle data from a TeslaMate PostgreSQL database, including status, trips, charging, efficiency, weather integration, and more, via 38 tools for MCP-compatible clients like Claude Code.38MIT