使用说明
hevy mcp
MCP服务器 Hevy 训练追踪API（v1）。将Hevy数据公开为Claude Desktop、Claude Code或任何MCP客户端可以调用的工具。
默认情况下为只读。通过 --write 启用变异工具（创建、更新、删除）。
OpenClaw特定的入职培训和sidecar设置： OPENCLAW.md.
入门指南
1.获取一个笨重的API密钥
从Hevy帐户设置生成API密钥（需要活动的Hevy订阅）。
2.设置您的环境
cp .env.example .env
编辑 .env 并添加您的API密钥：
HEVY_API_KEY=your-api-key-here
3.建造
cd hevy-mcp
pnpm install
pnpm build
4.本地测试
运行MCP检查器以验证服务器是否启动，并交互式浏览工具：
pnpm inspect
这将打开一个web UI，您可以在其中查看注册的工具，并根据实时API调用它们。你也可以跑步 pnpm start 验证服务器启动时没有错误。
5.配置您的MCP客户端
服务器自动加载 .env 从项目根目录（相对于构建的JS解析，因此无论工作目录如何，它都能工作）。如果您已经设置 .env 在步骤2中，配置只需要命令和路径：
{
"mcpServers": {
"hevy": {
"command": "node",
"args": ["/absolute/path/to/hevy-mcp/build/index.js"]
}
}
}
或者，您可以通过配置传递密钥 env 块而不是使用 .env 文件：
{
"mcpServers": {
"hevy": {
"command": "node",
"args": ["/absolute/path/to/hevy-mcp/build/index.js"],
"env": {
"HEVY_API_KEY": "<your-hevy-api-key>"
}
}
}
}
示例配置提供在 docs/claude-config-example.json.
要启用写访问（创建/更新/删除），请添加 "--write" 到 args:
"args": ["/absolute/path/to/hevy-mcp/build/index.js", "--write"]
工具
读取工具（始终启用）
| 工具 | 说明 |
|---|---|
list_workouts |
使用分页和日期过滤器列出训练 |
get_workout |
按ID获取单次锻炼 |
get_workout_count |
获取锻炼总数 |
get_workout_events |
获取某个日期以来的锻炼事件（创建/更新/删除） |
list_routines |
列出带分页的例程 |
get_routine |
按ID获取单个例程 |
list_exercise_templates |
列出带分页的练习模板 |
get_exercise_template |
按ID获取单个练习模板 |
list_routine_folders |
列出带分页的常规文件夹 |
get_routine_folder |
按ID获取单个例程文件夹 |
编写工具（必需 --write)
| 工具 | 说明 |
|---|---|
create_workout |
通过练习和套装创建新的锻炼计划 |
update_workout |
更新现有训练 |
delete_workout |
删除训练 |
create_routine |
创建新例程 |
update_routine |
更新现有例程 |
delete_routine |
删除例程 |
create_exercise_template |
创建自定义练习模板 |
create_routine_folder |
创建例程文件夹 |
update_routine_folder |
重命名例程文件夹 |
delete_routine_folder |
删除例程文件夹 |
建筑
hevy-mcp/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ ├── index.ts # Entry point
│ ├── env.ts # .env loader (resolves relative to project root)
│ ├── hevy-client.ts # Hevy API HTTP client
│ └── tools/
│ ├── read.ts # Read-only tool registrations
│ └── write.ts # Mutating tool registrations
└── build/ # Compiled output (git-ignored)
入口点(src/index.ts)
验证 HEVY_API_KEY 环境变量，解析 --write CLI标志，创建客户端和服务器，注册工具，并通过stdio连接。如果未设置API密钥，服务器将立即退出并返回错误。
HTTP客户端(src/hevy-client.ts)
HevyClient 将Hevy REST API封装在 https://api.hevyapp.com.它通过 api-key 在每个请求上显示标头并公开 get, post, put，以及 delete 方法。A. getAll 助手自动分页列表端点并返回组合结果。
工具注册(src/tools/)
工具分为两个模块-- read.ts 和 write.ts --每次导出一个 register*Tools(server, client) 功能。这种分离允许入口点仅在以下情况下有条件地加载写工具 --write 传递，默认情况下保持服务器只读。
每个工具都使用Zod模式进行输入验证（由MCP SDK自动处理），并返回JSON响应作为文本内容。
设计决策
- 默认情况下为只读。 写入工具可通过以下方式选择加入
--write以防止意外突变。这与此仓库中兄弟MCP服务器使用的模式相匹配。 - API上的薄包装。 工具以最小的转换直接映射到Hevy API端点。服务器将结构化的JSON响应传递给LLM，以便它可以自己解释数据。
- 自动分页。
getAll迭代分页端点的所有页面，对于需要完整数据集的工具或工作流非常有用。 - 没有令牌刷新。 与基于OAuth的API不同，Hevy使用静态API密钥，因此不需要刷新流。
文档
docs/architecture.md--系统图、模块分解、数据流docs/decisions.md--关键设计选择背后的基本原理docs/api-capabilities.md-您可以使用Hevy API、数据模型和示例用例做些什么docs/claude-config-example.json--复制粘贴MCP客户端配置
