Garmin MCP

项目状态（2026-08-23）：personal-tunnel 实现；本地冒烟测试通过。 不要启用好友访问或公共 MCP 入口。真实的 Garmin 凭据将保持阻止状态，直到 操作者明确批准单独的公共 HTTPS link-web 隧道，并完成 PERSONAL_TUNNEL_RUNBOOK.md 中的上线测试检查清单。

多用户、只读的 MCP 资源服务器，封装了 cyberjunky/python-garminconnect。它在不接收用户 ID 作为工具参数的情况下，暴露经过认证的 Garmin 数据。

安全模型

以下要点描述了原始设计意图。当前实现尚未完全验证所有这些要点；已知的缺口和必需的验收测试在 DESIGN_DRAFT.md 中跟踪。

• MCP bearer 令牌与 Garmin 认证分开验证。生产环境 OIDC 会验证签名、issuer、audience、过期时间、必需作用域（scopes），并使用经过验证的 sub 声明。

• Garmin 的邮箱、密码和 MFA 验证码仅在各自的请求期间存在。它们不会被持久化或记录。Uvicorn 访问日志已禁用。

• 仅存储 python-garminconnect 序列化的会话 JSON，使用 AES-256-GCM 加密，并与所属主体（principal）绑定认证，因此密文无法在用户之间转移。

• MFA 客户端是进程本地、单次使用、所有者绑定的，并在五分钟后过期。

• 连接 URL 将带签名的一次性状态放在 fragment 中。外部 JavaScript 会清除该 fragment，并将状态移入 POST 主体，使其不会出现在 HTTP 和代理访问日志中。

• 断开连接会删除本地加密令牌。这不会撤销已签发的 Garmin 令牌；如果曾被可能泄漏，请在 Garmin 账户安全设置中撤销访问权限。

Related MCP server: garmin-mcp

个人 ChatGPT 隧道模式

个人设置特意使用两个监听器：

• SERVER_ROLE=mcp 位于环回端口 3000。只有 OpenAI Secure MCP Tunnel 可以访问此端口。

• SERVER_ROLE=link-web 位于环回端口 3001。单独的 HTTPS 隧道可以只暴露此监听器，从而允许手机输入 Garmin 凭据，而不会暴露 MCP 端点。

AUTH_MODE=tunnel 配置有一个 TUNNEL_PRINCIPAL_ID；这不是多用户模式。OpenAI 隧道是认证边界，除非明确启用容器隔离，否则服务器会拒绝组合模式或非环回绑定。端到端设置详见 PERSONAL_TUNNEL_RUNBOOK.md。

本地运行

需要 Python 3.12+、PostgreSQL 17 和 uv。

cp .env.example .env
# Fill secrets, then for local-only bearer authentication set AUTH_MODE=development.
uv sync --all-extras
psql "$DATABASE_URL" -f migrations/001_initial.sql
uv run garmin-mcp

或者，在创建 .env 后运行 docker compose up --build。Compose 仅将两个应用端口发布到 127.0.0.1，并且不发布 PostgreSQL。MCP 端点是 /mcp；健康端点是 /healthz。在开发模式下，bearer 值本身就是本地用户 ID。切勿将开发模式暴露到环回之外。

MCP 工具

• get_connection_status

• connect_garmin — 返回一个十分钟有效、单次使用的浏览器 URL

• get_profile

• disconnect_garmin

当前 Garmin 数据工具是只读的。disconnect_garmin 仅通过删除存储的会话来修改本地连接状态。账户凭据仅在浏览器连接页中输入，绝不会作为 MCP 工具参数提供。健康/活动工具尚未实现。

验证

uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run pip-audit

不要在 CI 中放入真实的 Garmin 凭据。任何未来的 live 线上测试都必须使用专门的账户和明确集成测试标记。