Polar MCP

This repository implements the boundaries in ADR 0001: a reusable Python Polar core, with thin read-only adapters for local MCP and the Claude Agent SDK.

The implementation is intentionally v4-first. It provides:

• automatic AccessLink v4 token refresh;
• isolated v4 and complementary v3 clients;
• bounded, exclusive-end date ranges and automatic v4 request chunking;
• normalized response envelopes with API provenance and units;
• recursive credential, user/device identifier, and precise-location redaction;
• bounded nested time series and top-level results;
• an in-memory TTL cache that never persists health data;
• MCP and Agent SDK tools that can only read sanitized data;
• a separate authentication CLI with an owner-only local token file.

Install

Python 3.11 or later is required.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[mcp]'

Register an application in Polar AccessLink, then set server-side credentials. Do not put these values in an MCP configuration file that a model can read.

export POLAR_CLIENT_ID='...'
export POLAR_CLIENT_SECRET='...'

Generate an authorization URL with a state value that your callback verifies:

polar-auth authorization-url \
  --redirect-uri 'http://127.0.0.1:8787/callback' \
  --state "$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

After approving access, exchange the returned code. Omitting --code reads it without echoing it or placing it in shell history.

polar-auth exchange --redirect-uri 'http://127.0.0.1:8787/callback'
polar-auth status

Tokens default to the platform configuration directory and are rejected if their file is readable by anyone except its owner. Override the location with POLAR_TOKEN_FILE.

Run local MCP

polar-mcp

The server uses stdio; it does not open a network listener. It exposes only:

• polar_get_activity
• polar_get_sleep
• polar_get_recovery
• polar_get_training_sessions
• polar_get_heart_rate

All end_date values are exclusive. The tool schemas deliberately have no raw-data or location flags. Code outside an agent may use PolarService.query with an explicit DisclosureGrant, but the grant requires a separately recorded user confirmation and responses remain size-bounded.

Test

The tests use only the standard-library test runner and mocked HTTP transports:

PYTHONPATH=src python -m unittest discover -s tests -v

No test requires Polar credentials or sends health data over the network.

Current validation status

This code implements the durable architecture, but it does not claim the real-device proof of concept required to accept ADR 0001. The ADR remains Proposed until the documented live Polar Pacer checks are completed.