Garmin 只读 MCP

一个特意设计为窄范围的 Garmin Connect 集成，用于与 Hermes Agent 本地使用。它将选定的 Garmin 摘要同步到仅限所有者的 SQLite 缓存中，然后仅通过三个只读 MCP 工具提供该规范化缓存。

本项目使用社区维护的 python-garminconnect 客户端和未文档化的 Garmin Connect 端点。它与 Garmin 无关联，也未得到 Garmin 支持。端点可能发生变化，自动化访问可能带来账户或使用条款风险。官方 Garmin Connect 开发者计划仍是经批准的业务集成的首选途径。

安全模型

该设计将网络访问与 MCP 进程分离：

1. garmin-readonly-auth 在本地终端中执行一次性交互式登录。密码和 MFA 输入被隐藏，且从不接受作为命令参数。

2. garmin-readonly-sync 加载可重用的本地会话材料，获取有界日期窗口，剥离上游字段，并将规范化摘要写入 SQLite。

3. garmin-readonly-mcp 既不导入 Garmin 客户端也不导入会话材料。它仅读取规范化的 SQLite 缓存，并拒绝符号链接、非普通文件、非当前用户所有或组/其他用户可访问的缓存。

默认状态目录为：

~/.local/share/garmin-readonly-mcp/
├── tokens/          # Garmin session material, mode 0700/0600
└── cache.sqlite3    # normalized cache, mode 0600

设置非秘密的环境变量 GARMIN_READONLY_HOME 以使用其他根目录。切勿将状态目录放在仓库内部。

Related MCP server: garmin-mcp-local

数据范围

缓存和 MCP 仅暴露：

• 每日总热量、活动热量和基础代谢/静息热量

• 步数和静息心率（如有）

• 活动类型、开始时间、持续时间、距离和热量

• 睡眠时长/评分、身体电量、夜间 HRV/状态和训练准备度（如有）

它们特意排除：

• Garmin 个人资料和社交数据

• 账户标识符和活动 ID

• 设备详情

• GPS 坐标、路线和 FIT/GPX/TCX 文件

• 体重和身体成分

• 原始 Garmin 响应

• 上传、更新、计划或删除操作

• 通用或任意的 Garmin API 访问

Garmin 热量值是活动背景信息，并非增加食物摄入的指令。

要求

• Linux 或其他具有私有文件权限的类 Unix 环境

• Python 3.12+

• uv

• 一个 Garmin Connect 账户

安装

git clone https://github.com/alexpomsft/garmin-readonly-mcp.git
cd garmin-readonly-mcp
uv sync --frozen

本地认证

在私有的本地终端中运行此命令——不要在 Telegram、聊天、shell 历史记录或共享屏幕上运行：

uv run garmin-readonly-auth

该命令在本地询问电子邮件、隐藏密码，以及如果 Garmin 要求则隐藏的 MFA。它存储可重用的会话材料，但不存储密码。

同步

默认同步今天和昨天：

uv run garmin-readonly-sync

可以请求有界的历史窗口：

uv run garmin-readonly-sync --end-date 2026-08-18 --days 14

--days 必须在 1 到 31 之间。提供者错误将被替换为固定的公开消息，因此不会回显原始 Garmin 响应和认证详情。

运行 MCP 服务器

在至少一次成功同步之后：

uv run garmin-readonly-mcp

stdio 服务器精确暴露以下工具：

• get_daily_activity(date: YYYY-MM-DD)

• get_recent_activities(days: 1..31 = 7)

• get_recovery_summary(date: YYYY-MM-DD)

工具模式拒绝未声明的参数。

连接到 Hermes Agent

使用 Hermes 的 MCP 命令，而不是手动编辑 config.yaml：

hermes mcp add garmin-readonly \
  --command /absolute/path/to/garmin-readonly-mcp/.venv/bin/garmin-readonly-mcp
hermes mcp test garmin-readonly

添加服务器后重启 Hermes，以便发现其工具。不会将凭据或会话令牌路径传递给 MCP 配置；它使用私有的默认状态根目录。如果自定义了 GARMIN_READONLY_HOME，请仅使用 hermes mcp add ... --env GARMIN_READONLY_HOME=/private/path 传递该非秘密设置。

开发与验证

uv sync --frozen
uv run pytest --cov=garmin_readonly_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src tests
uv run pip-audit

实现采用先编写失败测试的方式开发。CI 运行相同的测试、lint、类型检查和依赖审计关卡。

限制

• Garmin Connect 端点是逆向工程所得，可能随时中断且不另行通知。

• Garmin 可能对自动化客户端进行速率限制、挑战或锁定。

• 某些恢复字段在某些设备或日期上不可用，并返回 null。

• 本地缓存是一个快照；如果需要更新的数据，请单独安排 garmin-readonly-sync。

• 本项目不会自动修改热量目标或提供医疗建议。

有关凭据处理和漏洞报告，请参阅 SECURITY.md。