Hevy MCP (Remote)

hevy-mcp-remote：面向 Hevy Fitness 的托管式 / 网关就绪 MCP

分支说明。 这是 chrisdoc/hevy-mcp 的独立维护分支，重新打包后可用于多租户 MCP 网关。它将相同的 Hevy 工具封装在 supergateway 中，作为通过 HTTP 提供 MCP 流式 HTTP 协议（而非 stdio）的 OCI 镜像发布。本地 / stdio 场景（如 Claude Desktop、Cursor 等）请使用上游的 hevy-mcp npm 包。

这是一个用于 Hevy 健身追踪应用的模型上下文协议（MCP）服务，打包为由 supergateway 封装的 OCI 镜像，可部署在 MCP 网关后面。它在 /mcp 上提供 MCP 流式 HTTP，在 /healthz 上提供健康状态检查；并从容器环境读取 HEVY_API_KEY。

---

📋 目录

• 功能
• 快速开始
• 先决条件
• 安装
  • Claude Desktop 配置
  • Cursor 配置
• 为什么选择 hevy-mcp？
• 配置
• 可用的 MCP 工具
• 开发与贡献

---

🚀 功能

• 训练管理：获取、创建和更新训练。
• 训练计划管理：访问和管理训练计划。
• 动作模板：浏览可用的动作模板，并使用内存缓存。
• 文件夹整理：管理训练计划文件夹。
• Webhook 订阅：为训练事件创建、查看和删除 Webhook 订阅。

---

🏁 快速开始

选择适合你设置的工作流：

场景	命令	要求
一次性 stdio 运行	HEVY_API_KEY=sk_live... npx -y hevy-mcp	Node.js ≥ 24，Hevy API 密钥
本地开发	npm install && npm run build && npm start	.env 中配置 HEVY_API_KEY

---

🛠️ 先决条件

• Node.js：v24 或更高版本（强烈建议使用 .nvmrc 中固定的确切版本）。
• npm：v10 或更高版本。
• Hevy API 密钥：所有操作都需要（Hevy PRO 用户可用）。

---

📦 安装

通过 npx 运行（推荐）

你可以直接启动服务，无需克隆：

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

手动安装

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies
npm install

# Create .env and add your keys
cp .env.sample .env
# Edit .env and add your HEVY_API_KEY

---

🔗 集成

Claude Desktop 配置

要在 Claude Desktop 中使用此服务，请将以下内容添加到 claude_desktop_config.json：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

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

Cursor 配置

在 ~/.cursor/mcp.json 的 "mcpServers" 下添加此服务：

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

---

✨ 为什么选择 hevy-mcp？

• 🚀 高性能：采用 Oxc 工具链（oxlint/oxfmt）构建，可实现近乎即时的代码检查和格式化。
• 🛡️ 类型安全：使用 Zod 和由 Kubb 生成的 API 客户端实现完全类型安全。
• 📉 可观测性：内置 Sentry 监控，用于错误追踪和性能分析。
• ⚡ 优化：为动作模板提供内存缓存，以降低 API 延迟。

---

⚙️ 配置

通过以下方式提供 Hevy API 密钥：

1. 环境变量：HEVY_API_KEY（在 .env 或系统环境中）。
2. CLI 参数：--hevy-api-key=your_key（在 npm 脚本中放在 -- 之后）。

# Example .env
HEVY_API_KEY=your_hevy_api_key_here

📡 Sentry 监控

hevy-mcp 集成了 Sentry 监控，用于观察生产环境中的错误和使用情况。它会初始化 @sentry/node，默认启用追踪并禁用 PII 收集。

---

🐳 在 MCP 网关后运行（supergateway 契约）

MCP 服务本身仅使用 stdio 通信。对于多租户网关部署（例如 mcp-gateway-poc），此仓库提供了一个 Dockerfile，通过 supergateway 包装 stdio 二进制文件，以便单个容器提供 MCP streamable-HTTP。

镜像遵循所有由网关托管的 MCP 服务共用的契约：

• 在 0.0.0.0:$PORT 的 /mcp 路径上提供 MCP streamable-HTTP
• 在 /healthz 提供健康检查端点
• 有状态会话（支持 Mcp-Session-Id）
• 从容器环境中读取 HEVY_API_KEY，并传递给启动的 stdio 子进程

镜像会从 main 和任何手动创建的 GitHub 版本发布到 ghcr.io/rwestergren/hevy-mcp。可在本地使用以下命令构建：

docker build -t hevy-mcp:local .
docker run --rm -e HEVY_API_KEY=sk_live_... -p 8080:8080 hevy-mcp:local
curl http://localhost:8080/healthz

直接运行 hevy-mcp 的最终用户应使用上文介绍的 stdio/npx 流程；Docker 镜像面向网关运营者，而非个人客户端。

---

🛠️ 可用的 MCP 工具

类别	工具
训练	get-workouts、get-workout、create-workout、update-workout、get-workout-count、get-workout-events
训练计划	get-routines、get-routine-by-id、create-routine、update-routine
模板	get-exercise-templates、get-exercise-template、search-exercise-templates
文件夹	get-routine-folders、get-routine-folder、create-routine-folder
Webhooks	get-webhook-subscription、create-webhook-subscription、delete-webhook-subscription

---

👨‍💻 开发与贡献

常用命令

• 构建：npm run build
• Lint/格式化：npm run check（使用 oxlint/oxfmt）
• 单元测试：npx vitest run --exclude tests/integration/**
• 完整测试套件：npm test（需要 HEVY_API_KEY）

详细的高级工程师指南请参阅 AGENTS.md。

API 客户端生成

API 客户端使用 Kubb 根据 OpenAPI 规范自动生成：

npm run build:client

---

📄 许可证与致谢

• 许可证：MIT
• 鸣谢：Model Context Protocol、Hevy Fitness。

---

欢迎贡献！ 如有任何重大更改，请提交 issue 或 PR。