重型-mcp服务器

Name: 重型-mcp服务器
Author: tomtorggler

作者：tomtorggler6 星标更新：2025-10-25

安装使用来源：spider==github.com

项目介绍

Hevy Fitness MCP Server

一个模型上下文协议（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 - 创建新的训练计划文件夹

🚀 快速开始

先决条件

Hevy Pro订阅 - Hevy API仅对Pro用户开放
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
# 当提示时粘贴您的API密钥

部署到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 Desktop连接，请编辑您的配置文件（设置 > 开发者 > 编辑配置）：

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

重启Claude Desktop，您将看到可用的Hevy工具。

Cloudflare AI Playground

转到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同步最近的更改。

管理训练计划

"创建一个新的Push Day训练计划，包括卧推（4组，每组8-12次重复，100公斤）和肩推（3组，每组10次重复，60公斤）"

助手将使用repRange字段为具有重复范围的练习，如“8-12次重复”。

"更新我的上身训练计划，添加引体向上"

助手将使用update_routine修改现有训练计划。

创建自定义练习

"创建一个名为'Tom的特殊电缆飞鸟'的自定义练习，使用电缆机针对胸部肌肉"

助手将使用create_exercise_template与适当的肌肉群和设备类别。

组织训练计划

"创建一个名为'Summer 2024 Programs'的新文件夹"

助手将使用create_routine_folder来组织您的训练计划。

🔧 API细节

锻炼结构

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

title - 锻炼名称（必需）
startTime - 锻炼开始时间（必需，ISO 8601格式）
endTime - 锻炼结束时间（必需，ISO 8601格式）
routineId - 此锻炼所属的可选训练计划ID
description - 可选锻炼描述
isPrivate - 锻炼是否私有（可选，默认值：false）
exercises - 练习数组，每个练习包含：
- title - 来自模板的练习名称（必需）
- exerciseTemplateId - 从get_exercise_templates获取（必需）
- supersetId - 可选超级组ID（如果不在超级组中则为null）
- notes - 此练习的可选笔记
- sets - 组数据数组，每个组包含：
  - type - "warmup"、"normal"、"failure"或"dropset"（可选）
  - 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 - "warmup"、"normal"、"failure"或"dropset"（可选）
  - 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应用 - Hevy健身追踪应用

🛠️ 开发

项目结构

hevy-mcp-server/
├── src/
│   ├── index.ts          # 包含工具定义的MCP服务器实现
│   └── lib/
│       └── client.ts     # Hevy API客户端包装器
├── api.json              # Hevy API的OpenAPI规范
├── wrangler.jsonc        # Cloudflare Workers配置
└── package.json

添加新工具

要添加新的Hevy API功能：

在src/lib/client.ts中添加API方法
在src/index.ts的init()方法中定义工具
使用Zod进行输入验证
优雅地处理错误

示例：

this.server.tool(
  "tool_name",
  {
    param: z.string().describe("参数描述"),
  },
  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 instanceof Error ? error.message : "未知错误"}`
        }]
      };
    }
  }
);

🤝 贡献

欢迎贡献！

如何贡献

分叉仓库 并从main分支创建您的分支
做出更改 - 添加功能、修复错误或改进文档
测试您的更改 - 运行npm test和npm run type-check
遵循代码风格 - 运行npm run format和npm run lint:fix
提交Pull Request 并附带清晰的更改描述

开发环境设置

# 克隆您的分叉
git clone https://github.com/tomtorggler/hevy-mcp-server.git
cd hevy-mcp-server

# 安装依赖项
npm install

# 复制环境变量模板
cp .dev.vars.example .dev.vars
# 将您的Hevy API密钥添加到.dev.vars

# 启动开发服务器
npm start

# 运行测试
npm test

贡献领域

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

📝 许可证

无许可证 - 详情见LICENSE文件。

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