星战科技xingzhan.cloud
返回市场
重型-MCP

重型-MCP

作者：chrisdoc59 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

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

smithery徽章 许可证：MIT

这是一个实现模型上下文协议（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密钥：

  1. 环境变量（HEVY_API_KEY）
  2. 命令行参数（--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。

  1. 确保已安装依赖：pnpm install

  2. 在本地启动Smithery游乐场：

    pnpm run smithery:dev

    CLI会提示输入HEVY_API_KEY，调用createServer({ config })，并打开Smithery MCP游乐场。

  3. 构建可部署的包：

    pnpm run smithery:build

  4. 将仓库连接到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：

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

要设置HEVY_API_KEY秘密：

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

如果未设置秘密，集成测试步骤将被跳过，并显示一条消息，指出缺少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。对于重大更改，请先打开一个问题讨论你想要更改的内容。

致谢