Polar Mcp Unofficial

by davidmosiah

274 downloads

Not rated

GitHub

Other

Description

<h1 align="center">Polar MCP</h1> <div align="center"> <img src="assets/banner.png" alt="Polar MCP — Polar MCP for AI agents" width="85%" /> </div> <h3 align="center"> Give your AI agent your Polar Nightly Recharge, training load, PPI and HRV…

About

Details

Author: davidmosiah
Downloads: 274
Categories: Other

- Local‑first OAuth; tokens never leave your machine
- Exposes Polar data via MCP tools, prompts, and resources
- Privacy modes: summary, structured, raw (GPS redacted by default)
- Supports 16 Polar AccessLink OAuth scopes
- Built‑in diagnostics with doctor and connection_status
- Caching via optional SQLite cache

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Polar Mcp Unofficial

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

From the repository

Install with three npm commands: npx -y polar-mcp-unofficial setup (paste your Polar AccessLink client id and secret), npx -y polar-mcp-unofficial auth (opens browser for OAuth), then npx -y polar-mcp-unofficial doctor to verify readiness. Add the server to your MCP client config with command npx -y polar-mcp-unofficial. For Claude Desktop, run setup --client claude to write the snippet automatically.

`polar_data_inventory`

Inventory supported Polar data domains, auth scope requirements, privacy boundary and recommended first calls. Does not call Polar APIs or expose user data.

`polar_agent_manifest`

Machine-readable install, runtime and client guidance for AI agents. Does not call Polar or expose secrets.

`polar_capabilities`

Explain supported Polar data, privacy boundaries, recommended agent workflow and project links.

`polar_quickstart`

Personalized 3-step setup walkthrough for the human user. Adapts to current state (env vars set? token present? what's next?). Call this first when the user asks 'how do I connect Polar?'

`polar_demo`

Returns realistic example payloads of polar_daily_summary, polar_wellness_context, and polar_list_nightly_recharge so agents see the contract before calling real Polar APIs.

`polar_get_auth_url`

Generate a Polar OAuth authorization URL. Use this first when no local token exists.

`polar_exchange_code`

Exchange a Polar OAuth authorization code for local tokens. Tokens are stored locally with 0600 permissions and are never returned. Requires explicit user action: the user must complete browser OAuth and supply the authorization code (agents must not invent codes).

`polar_get_account_data`

Read Polar user account fields exposed by AccessLink. Requires profile:read.

`polar_list_activity`

List Polar daily activity records. Requires activity:read.

`polar_list_calendar`

List Polar calendar entries in a date range. Requires calendar:read.

`polar_list_continuous_samples`

List continuous sample records for a date range. Requires continuous_samples:read. Prefer polar_heart_series for agent-safe bounded HR series. Not medical advice.

`polar_heart_series`

Bounded heart-rate series from Polar continuous samples (agent-safe-series/v1). Exact stats on full-resolution samples plus a series capped at 500 points. Prefer polar_daily_summary first. Shared contract with garmin/strava/fitbit series tools. Not medical advice.

`polar_list_nightly_recharge`

List Nightly Recharge results in a date range. Requires nightly_recharge:read. Not medical advice.

`polar_list_ppi_samples`

List pulse-to-pulse interval samples in a date range. Requires ppi_data:read.

`polar_list_skin_contacts`

List skin contact periods in a date range. Requires skin_contact:read.

`polar_list_sleeps`

List Polar sleep records in a date range. Requires sleep:read. Not medical advice.

`polar_list_sleep_wake_vectors`

List sleep/wake vector records in a date range. Requires sleep:read. Not medical advice.

`polar_list_sports`

List sports available in the Polar ecosystem. Requires sports:read.

`polar_list_sport_profile_catalog`

Load Polar sport profile catalog. Requires sports:read.

`polar_list_sport_profiles`

List the user's Polar sport profiles. Requires sports:read.

`polar_list_subscriptions`

List user subscriptions and entitlements. Requires user_subscription:read.

`polar_list_temperature_measurements`

List temperature measurements in a date range. Requires temperature_measurement:read.

`polar_list_tests`

List Polar fitness/orthostatic/running test results in a date range. Requires tests:read.

`polar_list_training_sessions`

List Polar training sessions in a date range. Requires training_sessions:read.

`polar_list_training_targets`

List calendar training targets in a date range. Requires training_targets:read.

`polar_list_training_target_favorites`

List user training target favorites. Requires training_targets:read.

`polar_list_user_devices`

List devices registered to the Polar user. Requires devices:read.

`polar_get_route`

Load a Polar route by route id. Routes are GPS-sensitive; default privacy modes redact coordinates. Requires routes:read.

`polar_connection_status`

Check local Polar config, token file, Node version, privacy mode, cache readiness and optional MCP client readiness without calling Polar or exposing secrets.

`polar_cache_status`

Show optional local SQLite cache status. Enable with POLAR_CACHE=sqlite or POLAR_CACHE=true.

`polar_privacy_audit`

Return local privacy, cache, token-path and env-presence posture without revealing secret values.

`polar_revoke_access`

Delete the local Polar token file. Use only when the user explicitly wants to disconnect this MCP; revoke the remote grant from Polar if needed. Gated by explicit_user_intent: true (requires explicit user intent).

`polar_daily_summary`

Build a practical daily summary from Polar sleep, activity, Nightly Recharge and training data when available. Read-only and non-medical.

`polar_weekly_summary`

Build a weekly Polar scorecard with sleep, activity, Nightly Recharge, training load context, bottlenecks and actions. Read-only and non-medical.

`polar_wellness_context`

Normalize Polar Nightly Recharge, sleep and training load into the shared wellness_context shape for recommendation engines.

`polar_profile_get`

Read the canonical Delx Wellness profile shared with the other wellness MCP connectors (Nourish, Cycle Coach, CGM, etc.). Read-only. Profile stores only what the user typed during onboarding — never OAuth tokens, API keys, or biomarkers.

`polar_profile_update`

Persist a partial patch to the canonical Delx Wellness profile. Requires explicit_user_intent=true after the user confirms they want to save. Rejects secret-like fields (oauth, token, api_key, password, cookie, refresh, session).

`polar_onboarding`

Read-only. Return the 11-question Delx Wellness onboarding flow (en or pt-BR), the current shared profile, missing critical fields, and a cross-connector hint. Use this when the user starts a fresh wellness session and you need to fill out preferred_name, goals, devices, training context, nutrition, preferences, and safety.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "polar mcp unofficial": {
            "polar": {
                "command": "npx",
                "args": [
                    "-y",
                    "polar-mcp-unofficial"
                ]
            }
        }
    }
}

McpServers

{
    "polar": {
        "command": "npx",
        "args": [
            "-y",
            "polar-mcp-unofficial"
        ]
    }
}

<h1 align="center">Polar MCP</h1>

<h3 align="center">
Give your AI agent your Polar Nightly Recharge, training load, PPI and HRV data — locally.<br>
Local-first MCP server — <strong>tokens never leave your machine</strong>.
</h3>

> ⚡ One-command install with Delx Wellness for Hermes:
> npx -y delx-wellness-hermes setup — preconfigures this connector and the other 8 in a dedicated Hermes profile.
>
> Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.

---

Local-first MCP server that connects AI agents to your Polar training, sleep, Nightly Recharge and continuous-sample data.

> Unofficial project. Not affiliated with, endorsed by or supported by Polar Electro Oy. Polar is a trademark of its respective owner. Use this only with your own Polar account and in line with the Polar AccessLink API terms.

Built by David Mosiah for people who use Claude, Cursor, Hermes, OpenClaw or other MCP-compatible agents to think about training load, recovery and endurance - without copy-pasting numbers from Polar Flow.

Part of Delx Wellness, a registry of local-first wellness MCP connectors.

> If this connector helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.

Why this exists

Polar has one of the deepest training-physiology stacks among consumer wearables - Nightly Recharge, continuous samples, PPI (pulse-to-pulse intervals), training targets, sport profiles, orthostatic and fitness tests. The Polar AccessLink Dynamic API v4 exposes this data, but with 16 fine-grained OAuth scopes and a structure that's harder to navigate than typical consumer APIs.

This package handles the OAuth dance locally, normalizes responses across the v4 endpoints, redacts GPS by default, and exposes Polar through the Model Context Protocol. Tokens never leave your machine.

Setup in 60 seconds

You'll need a Polar AccessLink client (create one here) with redirect URI http://127.0.0.1:3000/callback.

npx -y polar-mcp-unofficial setup    # interactive: paste client id + secret
npx -y polar-mcp-unofficial auth     # opens browser, captures the OAuth code
npx -y polar-mcp-unofficial doctor   # verifies you're ready

Recommended scopes (request the ones matching the data you want):

activity:read calendar:read continuous_samples:read devices:read
nightly_recharge:read ppi_data:read profile:read routes:read
skin_contact:read sleep:read sports:read temperature_measurement:read
tests:read training_sessions:read training_targets:read user_subscription:read

Then add this to your MCP client config:

{
  "mcpServers": {
    "polar": {
      "command": "npx",
      "args": ["-y", "polar-mcp-unofficial"]
    }
  }
}

For Claude Desktop, run setup --client claude and the snippet is written for you.

Try it with your agent

Three things to ask first:

Use polar_connection_status to check setup, then run polar_daily_summary.
Give me a 5-line training brief for today.

Call polar_weekly_summary with response_format=json. Identify my biggest
training-load/recovery bottleneck and give me a next-week plan.

Use the polar_training_load_investigation prompt, after=2026-04-01.
Walk me through my recent training sessions + Nightly Recharge.

Data availability

This package uses the official Polar AccessLink Dynamic API v4. When this README says raw, it means the upstream Polar JSON for a supported endpoint - not raw device sensor streams.

| Data | Available | Notes |
|---|:---:|---|
| Daily activity + calendar | yes | Requires activity:read / calendar:read |
| Sleep + sleep/wake vectors | yes | Requires sleep:read |
| Nightly Recharge (recovery score) | yes | Requires nightly_recharge:read; supported devices |
| Training sessions + training targets | yes | Requires training_sessions:read / training_targets:read |
| Continuous samples (HR over time) | yes | Requires continuous_samples:read |
| PPI samples (pulse-to-pulse intervals, HRV-relevant) | yes | Requires ppi_data:read; supported devices |
| Temperature measurements | yes | Requires temperature_measurement:read; supported devices |
| Skin contact periods | yes | Requires skin_contact:read |
| Tests (fitness / orthostatic / running) | yes | Requires tests:read |
| Routes + GPS geometry | opt-in | GPS coordinates redacted unless raw mode |
| Sports + sport profiles + devices | yes | Catalog and user metadata |
| Live device telemetry | - | Not exposed by Polar AccessLink |

Tools

Start with these:

- polar_connection_status - verify local setup, scopes and readiness before calling Polar
- polar_data_inventory — inventory supported data domains, scopes, privacy modes and recommended first calls without calling Polar APIs.
- polar_daily_summary - sleep, activity, Nightly Recharge and training brief for today
- polar_weekly_summary - scorecard, comparison vs prior week, next-week plan

Auth & diagnostics

- polar_capabilities, polar_agent_manifest, polar_privacy_audit, polar_cache_status
- polar_get_auth_url, polar_exchange_code, polar_revoke_access

Account

- polar_get_account_data, polar_list_user_devices, polar_list_subscriptions

Activity & sleep

- polar_list_activity, polar_list_calendar
- polar_list_sleeps, polar_list_sleep_wake_vectors
- polar_list_nightly_recharge

Heart & physiology (date range)

- polar_list_continuous_samples, polar_list_ppi_samples
- polar_list_temperature_measurements, polar_list_skin_contacts

Training

- polar_list_training_sessions, polar_list_training_targets, polar_list_training_target_favorites
- polar_list_tests

Sports & routes

- polar_list_sports, polar_list_sport_profile_catalog, polar_list_sport_profiles
- polar_get_route - GPS coordinates redacted unless raw mode

Prompts

- polar_daily_checkin - practical daily training and recovery check-in
- polar_weekly_review - review trends across activity, sleep and recovery
- polar_training_load_investigation - investigate training sessions + recovery context

Resources

- polar://capabilities, polar://agent-manifest
- polar://summary/daily, polar://summary/weekly

Privacy & security

- OAuth tokens are stored in ~/.polar-mcp/tokens.json with 0600 permissions and are never returned by tools.
- The server never prints access or refresh tokens.
- POLAR_PRIVACY_MODE defaults to structured. Raw Polar JSON is opt-in via raw mode or per-call override.
- GPS route geometry is redacted in summary and structured modes - only raw mode exposes raw coordinates.
- The MCP client never sees access or refresh tokens.
- This is not medical advice. The server exposes user-authorized data for personal AI workflows, not diagnosis or training prescription.

Configuration

setup writes most of these into ~/.polar-mcp/config.json (0600). Manual env override is supported:

POLAR_CLIENT_ID=<client-id>
POLAR_CLIENT_SECRET=<client-secret>
POLAR_REDIRECT_URI=http://127.0.0.1:3000/callback
Optional
POLAR_SCOPES="activity:read calendar:read continuous_samples:read ..."
POLAR_PRIVACY_MODE=structured        # summary | structured | raw
POLAR_CACHE=sqlite                   # optional read-through cache
POLAR_TOKEN_PATH=~/.polar-mcp/tokens.json
POLAR_CACHE_PATH=~/.polar-mcp/cache.sqlite

Hermes / remote setup

npx -y polar-mcp-unofficial setup --client hermes --no-auth
npx -y polar-mcp-unofficial auth                      # run locally if browser auth is needed
npx -y polar-mcp-unofficial doctor --client hermes
hermes mcp test polar

After Hermes config changes, use /reload-mcp or hermes mcp test polar. Don't restart the gateway for normal data access.

If browser OAuth has to happen on a different machine than Hermes, run auth locally and copy ~/.polar-mcp/tokens.json to the server with chmod 600.

Requirements

- Node.js 20+
- A Polar AccessLink client at <https://admin.polaraccesslink.com> with redirect URI http://127.0.0.1:3000/callback

Development

git clone https://github.com/davidmosiah/polar-mcp.git
cd polar-mcp
npm install
npm test
npm run build

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Links

- npm: <https://www.npmjs.com/package/polar-mcp-unofficial>
- Docs site: <https://wellness.delx.ai/connectors/polar>
- Legacy docs: <https://polarmcp.vercel.app/>
- GitHub: <https://github.com/davidmosiah/polar-mcp>
- Delx Wellness registry: <https://github.com/davidmosiah/delx-wellness>
- Connector quality standard: <https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md>
- Polar AccessLink Dynamic API v4 docs: <https://www.polar.com/polar-api-v4/>

📧 Contact & Support

- 📨 support@delx.ai — general questions, integration help, partnerships
- 🐛 Bug reports / feature requests — GitHub Issues
- 🐦 Updates — @delx369 on X
- 🌐 Site — wellness.delx.ai

License

MIT - see LICENSE.

Disclaimer

This software is provided as-is. It is not a medical device, does not provide medical advice, and should not be used for diagnosis, treatment or training prescription. Always consult qualified professionals for medical or training concerns.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Description

About

Details

Jump to

Setting up with Highlight

From the repository

polar_data_inventory

polar_agent_manifest

polar_capabilities

polar_quickstart

polar_demo

polar_get_auth_url

polar_exchange_code

polar_get_account_data

polar_list_activity

polar_list_calendar

polar_list_continuous_samples

polar_heart_series

polar_list_nightly_recharge

polar_list_ppi_samples

polar_list_skin_contacts

polar_list_sleeps

polar_list_sleep_wake_vectors

polar_list_sports

polar_list_sport_profile_catalog

polar_list_sport_profiles

polar_list_subscriptions

polar_list_temperature_measurements

polar_list_tests

polar_list_training_sessions

polar_list_training_targets

polar_list_training_target_favorites

polar_list_user_devices

polar_get_route

polar_connection_status

polar_cache_status

polar_privacy_audit

polar_revoke_access

polar_daily_summary

polar_weekly_summary

polar_wellness_context

polar_profile_get

polar_profile_update

polar_onboarding

Claude Desktop / Cursor

McpServers

Why this exists

Setup in 60 seconds

Try it with your agent

Data availability

Tools

Prompts

Resources

Privacy & security

Configuration

Optional

Hermes / remote setup

Requirements

Development

Links

See also

📧 Contact & Support

License

Disclaimer

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`polar_data_inventory`

`polar_agent_manifest`

`polar_capabilities`

`polar_quickstart`

`polar_demo`

`polar_get_auth_url`

`polar_exchange_code`

`polar_get_account_data`

`polar_list_activity`

`polar_list_calendar`

`polar_list_continuous_samples`

`polar_heart_series`

`polar_list_nightly_recharge`

`polar_list_ppi_samples`

`polar_list_skin_contacts`

`polar_list_sleeps`

`polar_list_sleep_wake_vectors`

`polar_list_sports`

`polar_list_sport_profile_catalog`

`polar_list_sport_profiles`

`polar_list_subscriptions`

`polar_list_temperature_measurements`

`polar_list_tests`

`polar_list_training_sessions`

`polar_list_training_targets`

`polar_list_training_target_favorites`

`polar_list_user_devices`

`polar_get_route`

`polar_connection_status`

`polar_cache_status`

`polar_privacy_audit`

`polar_revoke_access`

`polar_daily_summary`

`polar_weekly_summary`

`polar_wellness_context`

`polar_profile_get`

`polar_profile_update`

`polar_onboarding`