Hevy MCP Server

Hevy MCP 服务

Hevy CLI

更喜欢使用终端？独立的 @chrisdoc/hevy-cli 软件包可直接从 Hevy API 读取训练记录、训练计划、练习和身体测量数据， 并可在明确确认后创建或更新这些资源。不支持删除。

npm install -g @chrisdoc/hevy-cli
export HEVY_API_KEY=your-hevy-api-key

hevy workouts list --page-size 10
hevy summary --weeks 4

在任意命令后添加 --json，即可用于脚本和管道。该 CLI 是独立的 Hevy API 客户端，并非 MCP 封装。完整命令参考、分页行为和退出代码请参阅 packages/cli/README.md。

hevy-mcp 是面向 Hevy 健身和训练追踪 应用的开源 Model Context Protocol (MCP) 服务。它通过经过身份验证的 Hevy API 请求，让 AI 助手读取、分析、创建和更新你的 Hevy 训练记录、 训练计划、练习模板和身体测量数据。

Node stdio/HTTP 适配器和 Cloudflare Worker 共用相同的 MCP 工具。 请参阅部署模式以选择传输方式，或查看 架构，了解工作区所有权、运行时范围 和支持的嵌入 API。

需要 Hevy API 密钥，可通过 Hevy PRO 获取。

效果展示

_{点击预览即可播放完整画质的 18 秒演示。}

在演示中，助手会检索真实的 Hevy 数据，并依据用户的训练历史， 回答一个包含多个部分的训练问题。

可以用它做什么？

• 分析训练进度： 一次工具调用即可汇总 1-12 周的训练和身体测量数据。
• 用自然语言提问： 查找近期训练、训练频率最高的动作、训练规律中的空档、训练计划详情或动作历史。
• 规划并记录训练： 创建或更新训练、训练计划、训练计划文件夹、自定义动作和身体测量数据。
• 搜索时避免冗长回复： 通过精简、适合 AI 处理的结果发现训练计划和动作模板。
• 从你偏好的 MCP 客户端连接： 使用托管的 Streamable HTTP 端点，或通过 Codex、Claude Desktop、Cursor 和其他客户端在本地运行。
• 无需安装即可开始： 直接连接到生产环境中的 Cloudflare Worker，无需 Node.js、下载安装包或 Docker 容器。
• 需要时保留本地控制： 使用 npx、bunx 或官方 Docker 镜像运行同一服务。

试着这样提问：

分析我过去六周的训练情况。按周显示训练次数、我训练频率最高的动作，以及任何明显的空档或不一致之处，并引用你使用的训练记录作为依据。

找出我的推日训练计划，并列出其中的动作和组数。

将我近期的身体测量数据与训练规律进行比较。

根据我保存的训练计划创建一条已完成的训练记录。在将记录写入 Hevy 之前，询问我是否有任何缺失的组结果。

Claude 集成

此代码库包含一个 Claude 插件，可连接到启用了 OAuth 的托管 MCP 端点，无需嵌入用户的 Hevy API 密钥。

Claude.ai 和 Claude Desktop

在 Claude 中，打开 Settings → Connectors → Add custom connector，然后输入：

https://mcp.hevy-mcp.dev/mcp

完成 OAuth 流程，并在提示时输入 Hevy API 密钥。Claude Desktop 和其他支持远程 MCP 连接器的客户端也可以使用同一远程端点。

Claude Code 和 Cowork

Claude 插件由 .claude-plugin/plugin.json 和 .mcp.json 定义。可在此公开代码库中安装，也可在发布后从 Claude Plugin Directory 安装。它会添加托管的 Hevy MCP 连接器以及 Hevy 训练技能。

托管服务如何处理数据，请参阅隐私政策。

快速开始

1. 获取 Hevy API 密钥

在 Hevy 的 API 设置中创建 API 密钥，然后将其妥善保管。目前，API 访问需要 Hevy PRO 订阅。

2. 将 hevy-mcp 连接到你的客户端

托管的 Cloudflare 端点是最快的入门方式。它在远程运行，因此你的客户端无需 Node.js、Bun、Docker 或本地服务进程。

连接到托管端点

生产环境 URL：

https://mcp.hevy-mcp.dev/mcp

该端点使用 Streamable HTTP。每次请求都要将 Hevy API 密钥作为 bearer token 发送。

Codex

Codex CLI、Codex 桌面应用和 IDE 扩展共用同一 MCP 配置。确保启动 Codex 的环境中有 Hevy API 密钥，然后添加托管服务：

export HEVY_API_KEY=your-hevy-api-key
codex mcp add hevy \
  --url https://mcp.hevy-mcp.dev/mcp \
  --bearer-token-env-var HEVY_API_KEY

Codex 在 MCP 配置中存储的是环境变量名称，而不是密钥本身。重启 Codex 或开始新会话，然后运行 codex mcp list，确认服务已配置。

其他 Streamable HTTP 客户端

接受远程 MCP URL 和固定标头的客户端通常使用以下格式：

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

具体配置键因客户端而异。托管服务要求客户端支持 Streamable HTTP 和固定的 Authorization 标头。

重要

请将 bearer 值视同密码。Worker 会针对每个请求使用 Hevy 验证该值，不会存储该值，并且仅会将其作为必需的 api-key 标头转发给 Hevy。

改为在本地运行

如果你更倾向于在自己的计算机上运行服务，或客户端无法为远程 MCP 请求附加固定的授权标头，请选择本地 stdio。

Codex

codex mcp add hevy \
  --env HEVY_API_KEY=your-hevy-api-key \
  -- npx -y hevy-mcp

Claude Desktop 或 Cursor

将此 mcpServers 条目添加到客户端配置中：

{
	"mcpServers": {
		"hevy": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

Google Antigravity

有两种方式可以为 Google Antigravity（agy）配置 Hevy MCP 服务：

选项 A：自动安装插件（推荐）

此方式使用内置插件系统：

插件会读取仓库根目录中的 mcp_config.json，以启动本地 stdio 服务。该配置有意不包含 API 密钥；服务会从主机环境中继承 HEVY_API_KEY，如下所述。这与下文所述的手动全局用户配置，以及配置托管 HTTP/OAuth 的仓库 .mcp.json 相互独立。

1. 安装插件：

   agy plugin install https://github.com/chrisdoc/hevy-mcp
   

2. 在主机 Shell 环境中提供 HEVY_API_KEY，以便 CLI 子进程继承该变量：

   • 持久设置： 在系统／Shell 配置中保存环境变量 HEVY_API_KEY：
     • macOS / Linux： 将其添加到 Shell 配置文件中（例如 ~/.zshrc 或 ~/.bashrc）：

       export HEVY_API_KEY="your-actual-api-key"
       

     • Windows： 将其添加到用户或系统环境变量中。在 PowerShell 中，可以运行：

       [Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")
       

   • 临时设置（仅当前会话）： 如果不想持久保存密钥，请在运行 agy 之前，在当前终端会话中导出该变量：

     export HEVY_API_KEY="your-actual-api-key"
     

选项 B：手动配置（不使用插件）

如果你更倾向于通过全局配置文件进行静态配置：

1. 打开全局 MCP 配置文件：

   • 位置： ~/.gemini/config/mcp_config.json

2. 在 mcpServers 键下添加 hevy 配置块。请确保将此条目与已配置的其他服务合并，而不是替换整个文件内容：

   {
   	"mcpServers": {
   		"hevy": {
   			"command": "npx",
   			"args": ["-y", "hevy-mcp"],
   			"env": {
   				"HEVY_API_KEY": "your-actual-api-key"
   			}
   		}
   	}
   }
   

常见的本地配置位置：

• macOS 上的 Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows 上的 Claude Desktop： %APPDATA%\Claude\claude_desktop_config.json
• Cursor： ~/.cursor/mcp.json

保存文件后，重启客户端或重新连接。

任意 stdio MCP 客户端

配置客户端，使其在子进程环境中设置 HEVY_API_KEY 并启动以下命令：

npx -y hevy-mcp

npx 需要 Node.js 20 或更高版本。保存配置后，重启客户端或重新连接。

{
	"mcpServers": {
		"hevy": {
			"command": "bunx",
			"args": ["hevy-mcp@latest"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

export HEVY_API_KEY=your-hevy-api-key
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

{
	"mcpServers": {
		"hevy": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"--env-file",
				"/absolute/path/to/hevy-mcp.env",
				"ghcr.io/chrisdoc/hevy-mcp:latest"
			]
		}
	}
}

你也可以通过 add-mcp 将 npm 服务添加到受支持的客户端：

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

3. 提出你的第一个问题

重启或重新连接 MCP 客户端后，试试以下问题：

• “总结一下过去四周的训练情况。”
• “我在 Hevy 中保存了哪些训练计划？”
• “显示我最近的三次训练。”
• “查找包含深蹲的动作模板。”
• “连接的是哪个 Hevy 账户？”

如果客户端支持工具确认，你的助手应在调用会修改数据的工具前请求批准。

工作原理

Hosted:  Your AI assistant  →  Streamable HTTP  →  Cloudflare Worker  →  Hevy API
Local:   Your AI assistant  →  MCP over stdio   →  local hevy-mcp     →  Hevy API

托管端点会为每个请求创建一个全新的 MCP 服务和 Hevy 客户端。 直接使用 bearer 身份验证时，会使用提供的 Hevy 密钥，并将成功验证的结果缓存 15 分钟，而不会持久化原始密钥。OAuth 则会将密钥加密后存储在授权记录中。这两种方式 都不会创建共享的 MCP 用户会话。本地服务遵循相同的工具契约，但通过进程环境 接收 Hevy 密钥。

无论使用哪种模式，读取工具都会检索数据；只有在助手调用变更工具时，这些工具才会创建或替换数据。

引导式提示词

这些由服务提供的 MCP 提示词可协调常见的多步骤工作流：

工具

hevy-mcp 注册了 23 个工具。只读工具可安全用于探索；创建和更新工具带有 MCP 变更注释，兼容的客户端可以请求确认。

| 锻炼 | get-workout-events | 列出自某个时间戳以来的锻炼更新和删除事件。 | | 锻炼 | create-workout | 在 Hevy 中创建一次已完成的锻炼。 | | 锻炼 | update-workout | 按 ID 更新锻炼元数据；必须提供 is_private，其他未提供的字段和所有动作保持不变。 | | 锻炼 | replace-workout-exercises | 替换所有动作和组；必须提供并更新 is_private，其他锻炼元数据保持不变。 | | 训练计划 | search-routines | 搜索训练计划标题，并返回精简元数据以供查找。 | | 训练计划 | get-routines | 列出自定义和默认锻炼训练计划。 | | 训练计划 | get-routine | 按 ID 获取一个训练计划及其动作配置。 | | 训练计划 | create-routine | 创建可重复使用的锻炼训练计划。 | | 训练计划 | update-routine | 替换现有训练计划的内容。 |

| 训练计划文件夹 | get-routine-folder | 按 ID 获取一个训练计划文件夹的元数据。 | | 训练计划文件夹 | create-routine-folder | 创建一个训练计划文件夹。 |

| 动作模板 | get-exercise-template | 按 ID 获取一个动作模板的完整元数据。 | | 动作模板 | search-exercise-templates | 按标题子字符串搜索完整的动作目录。 | | 动作模板 | create-exercise-template | 创建自定义动作模板。 | | 动作历史 | get-exercise-history | 获取一个动作模板过去完成的组。 | | 身体测量 | get-body-measurements | 列出带日期的身体测量数据。 | | 身体测量 | get-body-measurement | 获取某个日期的身体测量记录。 | | 身体测量 | create-body-measurement | 创建带日期的身体测量记录。 | | 身体测量 | update-body-measurement | 更新某个已有日期的身体测量数据。 | | 诊断 | feedback | 以简洁且保护隐私的方式报告问题或异常行为。 |

create-routine 和 update-routine 要求顶层提供 routine 封装，其中包含非空的 exercises 数组；每个动作必须至少包含一组，并且所有层级的字段都使用 snake_case：

{
	"routine": {
		"title": "Full Body A",
		"folder_id": 123,
		"notes": "First four exercises are the minimum viable workout",
		"exercises": [
			{
				"exercise_template_id": "30E293E3",
				"superset_id": null,
				"rest_seconds": 120,
				"notes": "Controlled active ROM",
				"sets": [
					{
						"type": "normal",
						"rep_range": {
							"start": 6,
							"end": 10
						}
					}
				]
			}
		]
	}
}

Hevy API 目前未提供用于删除锻炼、训练计划、训练计划文件夹、动作模板或身体测量数据的端点，因此没有对应的删除工具。

资源

托管的 Cloudflare 端点

生产环境中的 MCP 服务已上线：

https://mcp.hevy-mcp.dev/mcp

这是使用 hevy-mcp 最快捷的方式：无需安装任何内容，也无需在本地持续运行；它提供的 23 个工具与 npm 包和 Docker 镜像相同。

Cloudflare Worker 使用无状态的 Streamable HTTP，通过 POST /mcp 提供服务。 客户端必须将 Hevy API 密钥作为固定授权标头发送：

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

在此配置中，Bearer 值是你的 Hevy API 密钥，而不是 OAuth 令牌。Worker 会使用哈希密钥缓存成功的验证结果 15 分钟，不会在此直接路径上持久化原始密钥，并且只会将其作为 Hevy 所需的 api-key 标头转发到上游。

面向 Claude.ai 和其他远程 MCP 客户端的 OAuth

托管的生产 Worker 已配置 OAUTH_KV 命名空间绑定，因此可为无法发送固定标头的客户端（例如 Claude.ai 自定义连接器）提供完整的 OAuth 2.1 层。可自托管的 Worker 可按照 CONTRIBUTING.md 中的 OAUTH_KV 设置启用此功能：

• /.well-known/ 下的 RFC 8414 / RFC 9728 发现元数据
• 客户端 ID 元数据文档（CIMD）；动态客户端注册（/register）作为备用方案，并支持 PKCE 令牌交换（/token）
• /authorize 页面，可在其中粘贴一次 Hevy API 密钥；该密钥会通过 Hevy 验证，并加密存储在 OAuth 授权中

将以 /mcp 结尾的 Worker URL 添加为 Claude.ai 自定义连接器，然后在浏览器中完成授权流程。直接发送 Authorization: Bearer <hevy-api-key> 的请求仍可正常使用，不受任何影响——OAuth 层只是附加功能。撤销或轮换 Hevy 密钥会阻止后续使用该密钥访问 Hevy API；但这本身不会删除已存储的授权，也不会立即清除缓存的验证结果。

OAuth 访问令牌有效期为 7 天，刷新令牌有效期为 30 天。这样既能减少频繁按小时刷新的 KV 写入次数，也能为受支持的客户端保留自动刷新功能。

该端点不提供旧版 SSE 或 GET 事件流。如果未启用 OAuth 层，则需要 OAuth 发现、动态注册、CIMD 或令牌刷新的客户端都不兼容，除非它们能够发送上述固定自定义标头。

自托管 Worker

克隆干净的代码库后，可以通过 pnpm --dir packages/worker exec cf deploy 部署可移植的 TypeScript Cloudflare 配置，并获取一个 workers.dev URL。OAuth 需要你自己的 OAUTH_KV 命名空间；自定义域名、路由和可观测性目标则是可选的账户设置。有关设置以及自托管环境与仅供维护者使用的命名环境之间的区别，请参阅 CONTRIBUTING.md。

请参阅 CONTRIBUTING.md，了解如何部署 Cloudflare Worker 以实现可自托管的 Streamable HTTP。

高级配置

HEVY_API_KEY=your-hevy-api-key npx hevy-mcp --transport http --host 127.0.0.1 --port 3000

本地 MCP 端点为 http://127.0.0.1:3000/mcp；绑定到非环回地址需要单独设置环境变量 HEVY_MCP_HTTP_BEARER_TOKEN。Docker 部署必须显式发布端口：

docker run --rm -p 3000:3000 -e HEVY_API_KEY -e HEVY_MCP_HTTP_BEARER_TOKEN \\
  ghcr.io/chrisdoc/hevy-mcp:latest --transport http --host 0.0.0.0 --port 3000

此 Node HTTP 模式不同于上文所述的无状态 Cloudflare Worker HTTP 端点：Node 服务负责管理有状态的客户端会话，而 Worker 专为托管部署设计，且不会导入 Node 代码。

缓存行为

search-exercise-templates 和 hevy://exercise-templates 共用 服务级的内存目录缓存：

• 条目保留五分钟，缓存最多存放一个目录。
• 如果可能，并发的目录请求会共用正在进行的获取操作。
• search-exercise-templates 接受 refresh: true 以使缓存失效。
• 每个托管 Worker 请求都会获得新的目录缓存，以防止跨密钥共享。
• 每个本地 HTTP 会话都有自己的 MCP 服务和目录缓存；各会话之间不共享缓存。

本地 Node 遥测与隐私

已发布的 Node 构建默认启用项目遥测。未构建的源码运行（例如开发和探测脚本）默认禁用遥测，除非显式设置 HEVY_MCP_TELEMETRY=1。这仅适用于本地 Node 行为；Cloudflare Worker 不会导入 Node 遥测。启动 Node 前设置 HEVY_MCP_TELEMETRY=0，即可在任一模式下禁用所有项目遥测。在已发布的构建中，除字面值 0 以外的任何值都会保留启用状态的默认设置。作用域化的 Node 生命周期 Layer 负责启用遥测；导入软件包本身不会产生副作用。启用遥测的源码运行使用 Sentry 环境 development；已发布的构建使用 production。设置 SENTRY_ENVIRONMENT 可覆盖此标签，例如设为 qa 或 staging。主开关优先于 SENTRY_DSN 和软件包内置或运行时的 OTEL_COLLECTOR_TOKEN 凭据，因此禁用时不会创建遥测导出器或定期指标读取器，也不会发出遥测网络请求。SENTRY_DSN 仅适用于 Sentry；启用遥测时，空值只会禁用 Sentry 导出。

启用后，可采取行动的错误会发送到由 SENTRY_DSN 配置的 Sentry 项目；Sentry 性能追踪处于禁用状态。导出前会限制异常消息和堆栈的长度，并对其进行脱敏。设置 HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 可保留结构化追踪和指标，同时抑制这些详细信息。追踪和指标仍会发送到收集器： https://otel.chrisdoc.dev/v1/traces 和 https://otel.chrisdoc.dev/v1/metrics。本项目使用自己的 OpenTelemetry Collector；下游目标在该基础设施中配置。指标每 30 秒导出一次。有关 Cloudflare OTLP 导出和域名追踪，请参阅可观测性文档。

原始 API 密钥绝不会被导出。普通工具遥测可能包含一个根据密钥派生的短期、确定性 HMAC 假名，用于关联；feedback 使用单独且不受监测的路径。可采取行动的错误可能附带每次故障的诊断 ID 和 OTel 追踪 ID。有关遥测字段的限制和隐私约定，请参阅遥测数据字典。

异常消息和堆栈被视为诊断详细信息：其长度会受到限制，凭据、URL 和本地 home 路径会被脱敏；设置 HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 时则会将其完全移除。提示词、工具参数、工具结果、请求正文、API 密钥、原始标识符/查询、确切日期、训练/计划/文件夹/模板/身体测量内容、姓名/标题/描述/备注、测量值、任意客户端元数据，以及未经规范化的端点路径，均禁止收集。

安全与数据变更

• 请勿将 HEVY_API_KEY 存入版本控制、URL、日志或屏幕截图。
• 本地客户端通过子进程环境提供密钥。
• 直连托管客户端仅在 Authorization: Bearer 请求头中发送 Hevy 密钥；验证成功后会缓存验证结果，但不会持久化原始密钥。 OAuth 授权会加密存储密钥。两种方式都只会通过 api-key 请求头将密钥发送给 Hevy。
• 浏览器 MCP 请求必须来自同源，或与精确匹配的允许列表来源一致。默认允许列表包含 Claude.ai、ChatGPT、VS Code for the Web 和 github.dev；可自托管部署可通过 MCP_ALLOWED_ORIGINS 覆盖此设置。OAuth 授权表单的例外情况请参阅部署模式。
• 本地开发时，可将 .dev.vars.example 复制为 .dev.vars，以便为 MCP Inspector 禁用来源验证。PR 预览 Workers 使用相同的仅限开发环境设置，因为其浏览器来源是动态的。切勿在生产 Worker 上设置 MCP_DISABLE_ORIGIN_CHECK=true。
• 重试创建操作可能会产生重复项。常规更新会替换内容；训练元数据更新会保留未提供的字段和动作，而 replace-workout-exercises 会替换所有动作和组数。 请检查工具输入，并使用客户端确认。

故障排除

• 服务器未显示： 更改配置后，请重启 MCP 客户端或重新连接。
• npx 失败： 确认已安装 Node.js 20 或更高版本，然后在终端中运行 npx -y hevy-mcp --version。
• Codex 无法看到服务器： 运行 codex mcp list，确认存在 hevy 条目后，再启动新的 Codex 会话。
• Hevy API 返回 401： 密钥无效、已过期、已撤销或配置错误。请在 Hevy 的 API 设置中验证或创建有效密钥，然后重启客户端。
• 托管身份验证失败： 确认密钥属于 Hevy PRO 账户，并以 Authorization: Bearer <HEVY_API_KEY> 的形式发送。
• 本地身份验证失败： 确认密钥有效，并通过 HEVY_API_KEY 提供给 MCP 子进程。
• 需要诊断信息： 设置 HEVY_MCP_DEBUG=1。诊断输出会写入 stderr，不会干扰 stdout 上的 MCP 消息。

如果您发现 Bug 或有功能请求，请提交 Issue。

贡献

欢迎贡献。开发环境设置、测试流程、生成客户端工作流、Cloudflare Worker 部署和拉取请求规则均记录在 CONTRIBUTING.md 中。

请使用 mise 获取固定版本的 Node.js 和 pnpm，然后运行确定性单元测试流程。该流程不需要有效的 Hevy API 密钥：

MISE_AUTO_INSTALL=false mise install
MISE_AUTO_INSTALL=false mise exec -- pnpm install
MISE_AUTO_INSTALL=false mise exec -- pnpm run test:unit

许可证与致谢

• 许可证： MIT
• 致谢： Model Context Protocol 和 Hevy Fitness