hevy mcp/hevy cli（铁锈）
 
防锈工具 Hevy健身追踪应用 及其 API:
hevy-mcp：用于支持MCP的客户端的模型上下文协议服务器，例如
作为Claude Desktop、Cursor、LobeChat、LibreChat和IDE插件。
hevy-cli：用于脚本、shell自动化的直接命令行客户端，
以及应该运行一个命令并退出的代理技能。
两个二进制文件使用相同类型的Rust Hevy API客户端，不需要Node或 Python运行时。
需要Hevy PRO订阅 以访问Hevy API。
我应该用什么？
| 用例 | 使用此 | 为什么 |
|---|---|---|
| 您的AI客户端支持MCP工具，并可以保持工具服务器的配置 | hevy-mcp | 通过stdio或流式HTTP将Hevy操作作为MCP工具公开 |
| 您需要一次性的shell命令、脚本、cron作业或CI自动化 | hevy-cli | 运行一个命令，打印JSON，然后退出 |
| 您正在为Hevy access打包代理技能 | hevy-cli + skills/hevy | 技能可以直接调用二进制文件，而无需运行MCP服务器 |
| 您希望为托管或web客户端提供HTTP/SSE访问权限 | hevy-mcp --transport streamable-http | 在以下位置提供MCP端点 /mcp |
特性
- 锻炼管理 --获取、创建和更新训练
- 日常管理 --访问和管理锻炼程序和文件夹
- 练习模板 --浏览可用模板；创建自定义
- 运动历史 --查询任何练习模板的过去集合
- Webhook订阅 --创建、查看和删除webhook订阅
- 双重运输 --跑过
stdio（默认）或streamable-http上海证券交易所 - 直接命令行界面 —
hevy-cli提供JSON优先命令和保护写入
和 --confirm
- 代理技能 —
skills/hevy记录代理人应如何致电hevy-cli
快速开始
安装 hevy-mcp 通过二进制
macOS/Linux：
curl -fsSL https://raw.githubusercontent.com/Brandon168/hevy-mcp-rust/master/install.sh | shWindows（PowerShell）： 下载 hevy-mcp-windows-x86_64.zip 从 发布页面，提取 它，并放置 hevy-mcp.exe 在PATH中，或直接运行它：
.\hevy-mcp.exe --help安装 hevy-cli 通过发布资产
下载匹配项 hevy-cli-* 存档自 发布页面，提取 它和地点 hevy-cli 在你的 PATH.
Linux x86_64示例：
curl -L -o hevy-cli-linux-x86_64.tar.gz \
https://github.com/Brandon168/hevy-mcp-rust/releases/latest/download/hevy-cli-linux-x86_64.tar.gz
tar -xzf hevy-cli-linux-x86_64.tar.gz
chmod +x hevy-cli
sudo mv hevy-cli /usr/local/bin/
hevy-cli --help从源代码运行
git clone https://github.com/Brandon168/hevy-mcp-rust.git
cd hevy-mcp-rust
HEVY_API_KEY=sk_live_... cargo run --release --bin hevy-mcp
HEVY_API_KEY=sk_live_... cargo run --release --bin hevy-cli -- auth test先决条件
- Hevy PRO订阅 -访问Hevy API时需要。
- Hevy API密钥 — 生成API密钥 在
你的Hevy账户。
- 锈蚀1.75+ --仅在以下情况下需要 从源头建造 （预编译
二进制文件没有依赖关系）。
平台支持： 在macOS、Linux和Windows上运行。二进制完全 跨平台--cargo build --release在每个上生成一个本机可执行文件 平台(hevy-mcp.exe在Windows上）。注意：macOS和Linux经过测试 工作得很好。Windows和WSL应该可以工作，但目前尚未经过测试；反馈是 欢迎
安装和配置
API密钥
通过环境变量或CLI标志提供您的Hevy API密钥：
# Environment variable (recommended)
export HEVY_API_KEY=sk_live_your_key_here
# Or as a CLI flag
./hevy-mcp --hevy-api-key=sk_live_your_key_here你也可以把它放在 .env 项目根目录中的文件（自动加载 启动时）：
HEVY_API_KEY=sk_live_your_key_here永远不要承诺你的 .env 文件或API密钥。hevy-cli
使用 hevy-cli 直接使用shell、自动化或代理技能。它没有 启动MCP服务器。
hevy-cli auth test
hevy-cli workouts list --page 1 --page-size 10
hevy-cli workouts get --id
hevy-cli export workouts --weeks 3 --full
hevy-cli export routine-bundle --routine-id --weeks 3写入命令需要 --confirm:
hevy-cli routines create --input routine.json --confirm
hevy-cli webhooks delete --confirm要在构建发布二进制文件后安装本地技能包装器，请传递 代理运行时预期的目标：
cargo build --release --bin hevy-cli
./scripts/install-hevy-skill.sh /path/to/agent/skills/hevyhevy-mcp
使用 hevy-mcp 当具有MCP功能的客户端应该发现并调用Hewy工具时。 默认情况下，它作为服务器通过stdio运行，或者在请求时通过可流式传输的HTTP运行。
运输方式
| 标志 | 默认值 | 描述 |
|---|---|---|
--transport stdio | ✅ 默认 | JSON-RPC通过stdin/stdout——适用于Claude Desktop、Cursor等。 |
--transport streamable-http | -- | 上的HTTP服务器 --port （默认值为3000） /mcp |
| `--port | ||
| ` | 3000 | 可流式传输http模式的端口 |
所有标志也可以通过环境变量设置： MCP_TRANSPORT, MCP_PORT.
与AI客户端集成
光标/克劳德桌面（标准）
添加 ~/.cursor/mcp.json 或 claude_desktop_config.json:
{
"mcpServers": {
"hevy-mcp": {
"command": "/path/to/hevy-mcp",
"env": {
"HEVY_API_KEY": "sk_live_your_key_here"
}
}
}
}流式HTTP（SSE）
使用时 hevy mcp 与支持 streamable-http 运输（例如 LobeChat, Librechat，或 IDE插件):
- 启动服务器:
hevy-mcp --transport streamable-http --port 3333- 配置客户端:
- 端点URL: http://localhost:3333/mcp - 类型: Streamable HTTP （或 SSE)
注： 服务器支持完整的MCP over SSE实现。结果 的 initialize 呼叫通过SSE进行流式传输，而后续请求则使用 将标准HTTP POST发送到清单端点。可用的MCP工具
锻炼工具
| 工具 | 说明 |
|---|---|
get-workouts | 分页的锻炼列表（最新的第一个） |
get-workout | 按ID列出的单次锻炼 |
get-workout-count | 帐户中的锻炼总数 |
get-workout-events | 分页的锻炼更新/删除自某个日期以来的事件 |
create-workout | 记录一项新的锻炼，包括练习和训练集 |
update-workout | 修改现有训练 |
常规工具
| 工具 | 说明 |
|---|---|
get-routines | 分页的例程列表 |
get-routine | 按ID列出的单个例程 |
create-routine | 创建新的锻炼计划 |
update-routine | 更新现有例程 |
常规文件夹工具
| 工具 | 说明 |
|---|---|
get-routine-folders | 常规文件夹分页列表 |
get-routine-folder | 按ID列出单个文件夹 |
create-routine-folder | 创建新的例程文件夹 |
练习模板工具
| 工具 | 说明 |
|---|---|
get-exercise-templates | 分页的练习模板列表 |
get-exercise-template | 按ID列出的单个模板 |
get-exercise-history | 模板的过去设置（带可选日期范围） |
create-exercise-template | 创建自定义练习模板 |
Webhook工具
| 工具 | 说明 |
|---|---|
get-webhook-subscription | 查看当前webhook订阅 |
create-webhook-subscription | 注册新的webhook URL |
delete-webhook-subscription | 删除当前的webhook订阅 |
发展
项目结构
hevy-mcp-rust/
├── Cargo.toml # Package manifest and dependencies
├── .env # Local API key (not committed)
├── skills/
│ └── hevy/ # Agent skill wrapper for hevy-cli
├── scripts/
│ └── install-hevy-skill.sh
├── src/
│ ├── main.rs # hevy-mcp entry point
│ ├── lib.rs # Library root (exports client, tools, types)
│ ├── client.rs # HevyClient — typed REST API wrapper
│ ├── bin/
│ │ └── hevy-cli.rs # Direct command-line client
│ ├── types.rs # Serde + JsonSchema typed structs
│ └── tools.rs # HevyTools — all 20 MCP tool implementations
├── tests/
│ ├── cli_test.rs # hevy-cli command tests
│ ├── integration_test.rs # Full E2E tests (stdio & streamable-http)
│ ├── client_test.rs # Unit tests for HevyClient using wiremock
│ └── deserialize_test.rs # Verification of API response parsing
└── openapi-spec.json # Cleaned Hevy API specification测试与验证
我们对可靠性保持高标准。在提交更改之前，请始终运行：
cargo test- 模仿测试：我们使用
wiremock在client_test.rs验证HTTP
在不影响API的情况下进行交互。
- 集成握手:
integration_test.rs生成二进制文件进行验证
Stdio和SSE上的完整MCP生命周期。
- 模式验证：单元测试
tools.rs确保JSON模式保持不变
与参考实现兼容。
AI开发人员说明：添加新工具或更改类型时，请确保 更新相应的模拟client_test.rs并验证反序列化 在deserialize_test.rs.使用HEVY_BASE_URL向客户指出你的模拟 服务器。
许可证
该项目根据MIT许可证获得许可。
致谢
- 模型上下文协议 对于MCP
SDK和规范
- Hevy 用于他们的健身跟踪平台和API
- chrisdoc/hevy mcp --原件
从中移植的TypeScript实现