重型-MCP

Name: 重型-MCP
Author: chrisdoc

作者：chrisdoc59 星标更新：2025-11-19

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

项目介绍

hevy-mcp: 与Hevy健身追踪应用API交互的模型上下文协议服务器

这是一个实现模型上下文协议（MCP）服务器，用于与Hevy健身追踪应用及其API进行交互。此服务器使AI助手能够通过Hevy API访问和管理锻炼数据、训练计划、运动模板等（需要PRO订阅）。

功能

锻炼管理：获取、创建和更新锻炼
训练计划管理：访问和管理训练计划
运动模板：浏览可用的运动模板
文件夹组织：管理训练计划文件夹
Webhook订阅：创建、查看和删除锻炼事件的webhook订阅

注意：HTTP传输和Docker镜像已被弃用。Smithery部署现在使用官方的TypeScript运行时流程（无需Docker），或者你可以通过stdio本地运行服务器（例如npx hevy-mcp）。现有的GHCR镜像仍然可用但不再更新。

先决条件

Node.js（v20或更高版本）
pnpm（通过Corepack）
Hevy API密钥

安装

通过npx运行（推荐）

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

HEVY_API_KEY=你的hevy_api_key_here npx -y hevy-mcp

手动安装

# 克隆仓库
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# 安装依赖
corepack use pnpm@10.22.0
cp .env.sample .env
# 编辑.env并添加你的Hevy API密钥

与Cursor集成

要使用此MCP服务器与Cursor集成，你需要更新你的~/.cursor/mcp.json文件，添加以下配置：

{
  "hevy-mcp-server": {
    "command": "npx",
    "args": ["-y", "hevy-mcp"],
    "env": {
      "HEVY_API_KEY": "你的api_key_here"
    }
  }
}

确保将你的api_key_here替换为你实际的Hevy API密钥。

配置

你可以通过两种方式提供Hevy API密钥：

环境变量（HEVY_API_KEY）
命令行参数（--hevy-api-key=your_key 或 hevy-api-key=your_key 当使用pnpm脚本时在--之后）

在项目根目录创建一个.env文件（你可以从.env.sample复制），如果使用环境变量方法，则内容如下：

HEVY_API_KEY=你的hevy_api_key_here

将你的hevy_api_key_here替换为你实际的Hevy API密钥。如果你更喜欢命令行参数的方法，可以跳过设置环境变量，并使用例如以下命令启动服务器：

pnpm start -- --hevy-api-key=你的hevy_api_key_here

传输

通过Smithery部署（TypeScript运行时）

Smithery可以通过导入从src/index.ts导出的createServer和configSchema来捆绑和托管hevy-mcp，无需Docker。

确保已安装依赖：pnpm install
在本地启动Smithery游乐场：
```
pnpm run smithery:dev
```
CLI会提示输入HEVY_API_KEY，调用createServer({ config })，并打开Smithery MCP游乐场。
构建可部署的包：
```
pnpm run smithery:build
```
将仓库连接到Smithery并通过其仪表板触发部署。配置完全通过导出的Zod模式处理，因此不需要额外的smithery.yaml环境映射。

hevy-mcp现在仅通过stdio运行，这与支持MCP的客户端如Claude Desktop和Cursor无缝工作。为了简化部署，已经移除了HTTP传输。

使用

开发

pnpm run dev

这将以热重载模式启动MCP服务器。

生产

pnpm run build
pnpm start

Docker（已弃用）

基于Docker的工作流已被淘汰，以便专注于原生stdio体验。捆绑的Dockerfile现在会退出并显示明确的消息以防止意外构建，.dockerignore简单地记录了弃用情况。之前发布的镜像仍然可以在GHCR上找到（例如ghcr.io/chrisdoc/hevy-mcp:latest），但它们不再更新。为了获得最佳体验，请通过npx hevy-mcp或你自己的Node.js运行时本地运行服务器。

可用的MCP工具

该服务器实现了以下MCP工具，用于与Hevy API交互：

锻炼工具

get-workouts：获取并格式化锻炼数据
get-workout：通过ID获取单个锻炼
create-workout：创建新的锻炼
update-workout：更新现有锻炼
get-workout-count：获取锻炼总数
get-workout-events：获取锻炼更新/删除事件

训练计划工具

get-routines：获取并格式化训练计划数据
create-routine：创建新的训练计划
update-routine：更新现有训练计划
get-routine-by-id：通过直接端点使用ID获取单个训练计划

运动模板工具

get-exercise-templates：获取运动模板
get-exercise-template：通过ID获取模板

训练计划文件夹工具

get-routine-folders：获取训练计划文件夹
create-routine-folder：创建新的文件夹
get-routine-folder：通过ID获取文件夹

Webhook工具

get-webhook-subscription：获取当前webhook订阅
create-webhook-subscription：创建新的webhook订阅
delete-webhook-subscription：删除当前webhook订阅

项目结构

hevy-mcp/
├── .env                   # 环境变量（API密钥）
├── src/
│   ├── index.ts           # 主入口点
│   ├── tools/             # MCP工具实现目录
│   │   ├── workouts.ts    # 与锻炼相关的工具
│   │   ├── routines.ts    # 与训练计划相关的工具
│   │   ├── templates.ts   # 运动模板工具
│   │   ├── folders.ts     # 训练计划文件夹工具
│   │   └── webhooks.ts    # Webhook订阅工具
│   ├── generated/         # API客户端（生成代码）
│   │   ├── client/        # Kubb生成的客户端
│   │   │   ├── api/       # API客户端方法
│   │   │   ├── types/     # TypeScript类型
│   │   │   ├── schemas/   # Zod模式
│   │   │   └── mocks/     # 模拟数据
│   └── utils/             # 辅助实用工具
│       ├── formatters.ts  # 数据格式化辅助工具
│       └── validators.ts  # 输入验证辅助工具
├── scripts/               # 构建和实用脚本
└── tests/                 # 测试套件
    ├── integration/       # 与真实API的集成测试
    │   └── hevy-mcp.integration.test.ts  # MCP服务器集成测试

开发指南

代码风格

该项目使用Biome进行代码格式化和lint检查：

pnpm run check

测试

运行所有测试

要运行所有测试（单元测试和集成测试），使用：

pnpm test

注意：如果设置了HEVY_API_KEY环境变量，集成测试也会运行。如果没有设置，则只运行单元测试。

只运行单元测试

要只运行单元测试（排除集成测试）：

pnpm vitest run --exclude tests/integration/**

或者带覆盖率：

pnpm vitest run --coverage --exclude tests/integration/**

只运行集成测试

要只运行集成测试（需要有效的HEVY_API_KEY）：

pnpm vitest run tests/integration

注意：如果未设置HEVY_API_KEY环境变量，集成测试将会失败。这是设计如此，以确保测试始终使用有效的API密钥运行。

GitHub Actions配置

对于GitHub Actions：

单元测试将在每次推送和拉取请求时运行
集成测试只有在仓库设置中设置了HEVY_API_KEY秘密时才会运行

要设置HEVY_API_KEY秘密：

转到你的GitHub仓库
点击“设置” > “机密和变量” > “操作”
点击“新建仓库秘密”
将名称设置为HEVY_API_KEY，并将值设置为你的Hevy API密钥
点击“添加秘密”

如果未设置秘密，集成测试步骤将被跳过，并显示一条消息，指出缺少API密钥。

生成API客户端

API客户端从OpenAPI规范使用Kubb生成：

pnpm run export-specs
pnpm run build:client

Kubb从OpenAPI规范生成TypeScript类型、API客户端、Zod模式和模拟数据。

故障排除

Rollup可选依赖缺失：如果你看到类似无法找到模块 @rollup/rollup-linux-x64-gnu的错误，在运行pnpm run build前设置环境变量ROLLUP_SKIP_NODEJS_NATIVE_BUILD=true。这将强制Rollup使用纯JavaScript回退，并避免某些Linux运行器上的npm可选依赖项错误。

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。

贡献

欢迎贡献！请随时提交Pull Request。对于重大更改，请先打开一个问题讨论你想要更改的内容。

致谢

模型上下文协议为MCP SDK
Hevy为其健身追踪平台和API