使用说明

Hevy Fitness MCP 服务器

一个模型上下文协议（MCP）服务器，为人工智能助手提供访问权限 “Hevy”可以翻译为“重型”或“沉重”，具体取决于上下文和使用场景。如果是指物理上的重量或强度，通常翻译为“重型”；如果是指情感或语气上的强烈，则翻译为“沉重”。在没有具体上下文的情况下，两者都是可能的翻译健身追踪API。这允许您记录锻炼、管理常规、浏览锻炼项目，并直接通过AI聊天界面追踪您的健身进度。

🏋️ 功能特点

这款MCP服务器提供了对Hevy健身追踪功能的全面访问：

锻炼

get_workouts - 浏览您的锻炼历史（分页显示）
get_workout - 获取特定锻炼的详细信息
create_workout - 记录新的锻炼，包括练习项目、组数、重量和重复次数
update_workout - 更新现有的锻炼计划
get_workouts_count - 获取记录的总锻炼次数
get_workout_events - 获取自特定日期以来的锻炼变更事件（更新/删除）以进行同步

常规程序/日常程序

get_routines - 列出你的锻炼计划
get_routine - 获取特定例程的详细信息
create_routine - 创建一个新的锻炼计划模板
update_routine - 更新现有程序

练习

get_exercise_templates - 浏览可用练习（包括Hevy的库和您自定义的练习）
get_exercise_template - 获取特定练习模板的详细信息
create_exercise_template - 创建自定义练习模板
get_exercise_history - 查看你特定练习的过往表现历史

组织

get_routine_folders - 列出你的常规文件夹以便整理
get_routine_folder - 获取特定常规文件夹的详细信息
create_routine_folder - 创建一个新的程序文件夹

🚀 快速入门

先决条件

Hevy Pro 订阅服务 Hevy API仅供专业用户使用
Hevy API密钥 - 在 https://hevy.com/settings?developer 获取您的（账号/设置）
Cloudflare账户 - 用于部署MCP服务器

部署到 Cloudflare Workers

克隆此仓库：

git clone https://github.com/tomtorggler/hevy-mcp-server.git
cd hevy-mcp-server

安装依赖项：

npm install

设置您的Hevy API密钥为秘密：

npx wrangler secret put HEVY_API_KEY
# Paste your API key when prompted

部署到Cloudflare：

npm run deploy

您的MCP服务器将可用，访问地址为： https://hevy-mcp-server.<your-account>.workers.dev/mcp

本地开发

在本地运行服务器：

npm run dev

服务器将在以下地址可用： http://localhost:8787/mcp

🔌 连接到AI客户端

Claude Desktop（可译为“Claude桌面版”或根据具体语境简化为“Claude桌面”）

要在Claude Desktop上进行连接，请编辑您的配置文件（设置 > 开发者 > 编辑配置）：

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://hevy-mcp-server.<your-account>.workers.dev/mcp"
      ]
    }
  }
}

重启Claude桌面版后，您将看到可用的Hevy工具。

Cloudflare AI Playground（可译为“Cloudflare AI游乐场”或“Cloudflare AI试验场”）

访问 https://playground.ai.cloudflare.com/
输入您已部署的MCP服务器URL
直接在游乐场开始使用Hevy工具！

📖 使用示例

制定一个锻炼计划

一旦连接成功，您可以要求您的AI助手记录锻炼情况：

“记录一下今天的锻炼，时间是从上午10点到11点。我做了卧推：3组，每组100公斤，重复10次；还有深蹲：4组，每组120公斤，重复8次。”

助手将：

使用 get_exercise_templates 查找练习题ID
呼叫 create_workout 具有适当的结构
确认锻炼记录已成功录入

查看进度

“给我显示我最近5次的锻炼记录”

“我之前的硬拉训练记录是什么？”

“获取自2024年1月1日以来的所有锻炼更改”

助手将使用 get_workout_events 以同步最近的更改。

管理日常事务

“制定一个新的推举日训练计划，包括卧推（4组，每组8-12次，重量100公斤）和肩上推举（3组，每组10次，重量60公斤）”

助手将使用 repRange 用于进行“8-12次重复”等重复范围的练习的字段。

“更新我的上半身锻炼计划，加入引体向上”

助手将使用 update_routine 修改现有程序。

创建自定义练习

“使用绳索机为胸部设计一个名为‘汤姆的特殊绳索飞鸟’的自定义练习”

助手将使用 create_exercise_template 配备相应的肌肉群和设备类别。

组织日常事务

“创建一个名为‘2024年夏季项目’的新文件夹”

助手将使用 create_routine_folder 来组织你的日常事务。

🔧 API详情

锻炼结构

在创建锻炼计划时，您可以指定：

title - 锻炼名称（必填）
startTime - 当锻炼开始时（必填，ISO 8601格式）
endTime - 当锻炼结束时（必填，ISO 8601格式）
routineId - 可选：此锻炼所属的常规ID
description - 可选的锻炼描述
isPrivate - 训练是否为私人训练（可选，默认：否）
exercises - 一系列练习，每项均包含：
- title - 来自模板的练习名称（必填）
- exerciseTemplateId - 从……获取这个 get_exercise_templates （必填）
- supersetId - 可选的超集ID（若不属于任何超集，则为null）
- notes - 本练习的可选说明
- sets - 一组设置数据，包含：
  - type - “热身”、“正常”、“失败”或“递减组训练”（可选）
  - weightKg - 体重（公斤）（可选）
  - reps - 重复次数（可选）
  - distanceMeters - 有氧运动（可选）
  - durationSeconds - 对于定时练习（可选）
  - customMetric - 步数/楼层的自定义指标（可选）
  - rpe - 主观体力感觉评分，6-10分（可选）

注：这个（或“该”） index 根据其在数组中的位置，练习和集合的字段会自动生成。

常规结构

在创建常规程序时，您可以指定：

title - 例程的名称（必填）
folderId - 可选文件夹ID（默认为“My Routines”文件夹时设为null）
notes - 常规操作的可选说明
exercises - 一系列练习，每项包含：
- exerciseTemplateId - 从这里获取 get_exercise_templates （必填）
- supersetId - 可选的超集ID（如果未处于超集中，则为null）
- restSeconds - 组间休息时间（秒）（可选）
- notes - 本练习的可选说明/备注
- sets - 一组设置数据，包括：
  - type - “热身”、“正常”、“失败”或“递减组”（可选）
  - weightKg - 体重（公斤）（可选）
  - reps - 重复次数（可选）
  - repRange - 用范围对象表示重复范围 start 并且 end （可选，例如，8-12次重复）
  - distanceMeters - 用于有氧运动（可选）
  - durationSeconds - 对于计时练习（可选）
  - customMetric - 自定义步数/楼层指标（可选）

重要提示： 与锻炼不同，日常习惯并不使用（某种方法或工具） index 或者 title 练习/集合中的字段。这些是由API生成的。

时间格式

所有时间戳均采用ISO 8601格式：

2024-10-15T10:00:00Z

📚 资源

Hevy API 文档 - 官方API文档
MCP 文档 - 了解模型上下文协议
Hevy App（可译为“赫维应用”或根据具体语境调整为更贴切的名称，但“赫维”仅为音译，实际翻译需结合应用的具体内容或品牌策略） - Hevy健身追踪应用程序

🛠️ 开发

项目结构

hevy-mcp-server/
├── src/
│   ├── index.ts          # MCP server implementation with tool definitions
│   └── lib/
│       └── client.ts     # Hevy API client wrapper
├── api.json              # OpenAPI specification for Hevy API
├── wrangler.jsonc        # Cloudflare Workers configuration
└── package.json

添加新工具

为添加新的Hevy API功能：

将API方法添加到 src/lib/client.ts
在（某处）定义该工具 src/index.ts 在……里面 init() 方法
使用 Zod 进行输入验证
优雅地处理错误

示例：

this.server.tool(
  "tool_name",
  {
    param: z.string().describe("Parameter description"),
  },
  async ({ param }) => {
    try {
      const result = await this.client.someMethod(param);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
        }]
      };
    }
  }
);

🤝 贡献

欢迎投稿！

如何做出贡献

为仓库创建分支 并从（某个点/分支）创建你的分支 main
做出你的更改 - 添加功能，修复错误，或改进文档
测试你的更改 - 跑 npm test 并且 npm run type-check
遵循代码风格 - 跑 npm run format 并且 npm run lint:fix
提交拉取请求 对您的更改进行清晰描述

开发环境设置

# Clone your fork
git clone https://github.com/tomtorggler/hevy-mcp-server.git
cd hevy-mcp-server

# Install dependencies
npm install

# Copy environment variables template
cp .dev.vars.example .dev.vars
# Add your Hevy API key to .dev.vars

# Start development server
npm start

# Run tests
npm test

贡献领域

添加更多Hevy API终端点
改进错误处理和验证
增加更全面的测试
改进文档和示例
通过 Issues 报告错误或提出功能建议

📝 许可证

无许可协议 - 详见许可证文件中详述。

这个项目与Hevy无关。Hevy是Hevy Studios Inc.的商标。