Polar MCP

极地接入链路

polar-accesslink 是一个共享的Polar AccessLink核心，带有两个适配器：

• polar-mcp 适用于LLM和MCP兼容的客户端
• polar-cli 用于cronjobs、导出和简单自动化

当前范围包括 activities, cardio-load，以及 exercises.

建筑

• polar_accesslink.service 和 polar_accesslink.client 包含共享核心。
• polar_accesslink.mcp_server 通过MCP工具暴露核心。
• polar_accesslink.cli 通过终端命令公开相同的操作。

支持的操作

• activities_range(from_date, to_date, include_samples=false)
• activity_by_date(date, include_samples=false)
• cardio_load_recent(days=30)
• cardio_load_by_date(date)
• exercises_recent(include_samples=false, include_zones=false, include_route=false, include_tcx_metadata=false)
• exercise_by_id(exercise_id, include_samples=false, include_zones=false, include_route=false, include_tcx_metadata=false)

两个适配器都返回结构化的JSON信封：

• status: ok | no_data | error
• query
• data
• meta.generated_at
• meta.source
• meta.rate_limit

需求

• python 3.11+
• 极地接入链路 access_token
• 仅当您使用一次性OAuth引导帮助程序时，才使用Polar AccessLink客户端凭据

快速入门

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
export POLAR_ACCESS_TOKEN="your-access-token"

主控程序

polar-mcp

兼容性包装：

python3 run_polar_mcp.py

命令行界面

polar-cli activities-range --from-date 2026-04-01 --to-date 2026-04-07 --pretty
polar-cli exercises-recent --output jsonl --out data/exercises.jsonl

MCP配置示例

{
  "mcpServers": {
    "polar": {
      "command": "python3",
      "args": ["/absolute/path/to/run_polar_mcp.py"],
      "env": {
        "POLAR_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cron示例

0 6 * * * cd /absolute/path/to/polar-accesslink && . .venv/bin/activate && POLAR_ACCESS_TOKEN=your-access-token polar-cli exercises-recent --output json --out data/exercises.json

OAuth引导助手

polar_auth.py 现在是一个薄薄的包裹 scripts/polar_auth.py，它仍然是一个独立的一次性助手，用于：

1. 在上启动回调服务器 127.0.0.1:3000
2. 打开Polar身份验证URL
3. 令牌的交换代码
4. 用户可以选择注册 POST /v3/users

在运行之前，请创建Polar AccessLink客户端并配置重定向URL 使用官方Polar文档：

• https://www.polar.com/accesslink-api/?srsltid=AfmBOorLohdyoKgJzuBTMkXHdaePysjJjcxexJQiq5ZH5UyDWFS_3aK8#authentication

例子：

export POLAR_CLIENT_ID='your-client-id'
export POLAR_CLIENT_SECRET='your-client-secret'
export POLAR_REDIRECT_URI='http://127.0.0.1:3000/auth/polar/callback'
export POLAR_MEMBER_ID='your-member-id'
python3 polar_auth.py

迁移说明

• Python包已更改 polar_mcp 到 polar_accesslink.
• 分发名称已更改 polar-mcp 到 polar-accesslink.
• polar-mcp 保持为MCP可执行文件。
• run_polar_mcp.py 保留为兼容性包装器，但现在导入重命名的模块。
• 新的自动化入口点： polar-cli.
• 如果您有直接的Python导入、cronjobs或MCP配置固定到旧模块路径，请在升级前更新它们。

隐私和出版

• 不要承诺 .env 文件或真实的Polar凭据。
• 不要发布原始锻炼导出(.tcx, .fit, .gpx)除非你愿意公开这些数据。
• exercise_by_id(..., include_tcx_metadata=true) 可以从TCX导出中显示锻炼标题和笔记。

已知限制

• activities 是日间总结/示例，而不是锻炼会话对象。
• cardio-load 是只读的负载状态/历史数据。
• exercise JSON不公开训练 title/notes.
• include_tcx_metadata=true 每次练习都会提出额外的TCX请求，以丰富 title 和 notes.
• TCX title 限制为15个字符 --Garmin TCX XSD模式定义 Plan/Name 作为 RestrictedToken_t (maxLength=15).Polar会截断较长的标题以符合规范 notes 现场(xsd:string)没有长度限制。如果您需要完整的练习描述，请将其放在极流中的注释字段中。
• GPX 只有当锻炼有路线数据时，数据才可用。

待办事项

• 为添加原始导出助手 FIT 和 GPX 必要时。