AI导哈

健身追踪MCP服务器

一个模型上下文协议（MCP）服务器，为AI助手提供访问Hevy健身追踪API的能力，支持记录锻炼、管理日常、浏览练习和追踪健身进度。

  • by jonathancaudill
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jonathancaudill/hevy-mcp-server

使用说明

Hevy Fitness MCP 服务器

一个模型上下文协议（MCP）服务器，为AI助手提供访问权限 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 - 创建一个新的常规文件夹

🚀 快速入门

先决条件

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

部署到 Cloudflare Workers

  1. 克隆此仓库：
git clone https://github.com/tomtorggler/hevy-mcp-server.git
cd hevy-mcp-server
  1. 安装依赖项：
npm install
  1. 设置您的Hevy API密钥为机密：
npx wrangler secret put HEVY_API_KEY
# Paste your API key when prompted
  1. 部署到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 Desktop上进行连接，请编辑您的配置文件（设置 > 开发者 > 编辑配置）：

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

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

Cloudflare AI 实验场

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

📖 使用示例

制定锻炼计划

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

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

助手将：

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

查看进度

“给我显示我最近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-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功能：

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

示例：

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"}`
        }]
      };
    }
  }
);

🤝 贡献

欢迎投稿！

如何贡献（或如何参与贡献）

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

开发环境设置

# 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 报告错误或提出功能建议

📝 许可证

MIT 许可证 - 请参阅 许可证 文件中有详细信息。

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

相关 MCP