Polar MCP

本仓库实现了 ADR 0001 中定义的边界：一个可复用的 Python Polar 核心，以及面向本地 MCP 和 Claude Agent SDK 的轻量只读适配器。

该实现特意以 v4 为先。它提供：

• 自动刷新 AccessLink v4 令牌；

• 相互隔离的 v4 客户端和互补的 v3 客户端；

• 有界、终点不包含在内的日期范围，以及自动的 v4 请求分块；

• 带有 API 来源和单位的规范化响应封装；

• 对凭据、用户/设备标识符和精确位置的递归脱敏；

• 有界的嵌套时间序列和顶层结果；

• 一个从不持久化健康数据的内存 TTL 缓存；

• 只能读取已脱敏数据的 MCP 和 Agent SDK 工具；

• 一个独立的身份验证 CLI，其本地令牌文件仅所有者可读。

安装

需要 Python 3.11 或更高版本。

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

在 Polar AccessLink 中注册一个应用程序，然后设置服务端凭据。不要将这些值放入模型可以读取的 MCP 配置文件中。

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

生成带有 state 值的授权 URL，你的回调会验证该值：

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

批准访问后，交换返回的 code。省略 --code 时，读取该值不会回显，也不会将其放入 shell 历史记录。

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

令牌默认存放在平台配置目录中；如果文件可被所有者以外的任何人读取，则会被拒绝。可使用 POLAR_TOKEN_FILE 覆盖该位置。

Related MCP server: health-mcp

运行本地 MCP

polar-mcp

服务器使用 stdio；它不会打开网络监听器。它只暴露：

• polar_get_activity

• polar_get_sleep

• polar_get_recovery

• polar_get_training_sessions

• polar_get_heart_rate

所有 end_date 值均不包含端点日期。工具模式刻意不包含原始数据或位置标志。代理之外的代码可以使用显式 DisclosureGrant 调用 PolarService.query，但该授权需要单独记录的用户确认，并且响应仍保持大小有界。

测试

测试仅使用标准库测试运行器和模拟的 HTTP 传输：

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

没有任何测试需要 Polar 凭据，也不会通过网络发送健康数据。

当前验证状态

此代码实现了持久架构，但并未声称已完成接受 ADR 0001 所需的真实设备概念验证。在文档中记录的 Polar Pacer 实机检查完成之前，该 ADR 仍保持 Proposed 状态。