Skip to main content
Glama
Garmin Read-Only MCP

Garmin Read-Only MCP

by alexpomsft

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。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A local MCP server that caches Garmin Connect data in SQLite for fast, read-only queries, with tools for bulk import, rate-limited sync, and failure alerts.
      9
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server that exposes Garmin Connect health data from a local SQLite database to AI assistants, enabling queries for recent days, sleep, weekly trends, and a guarded SQL query surface.
      MIT