hevy-mcp: Hevy Fitness API 的模型上下文协议服务器

一个模型上下文协议 (MCP) 服务器的实现，它与 Hevy 健身追踪应用 及其 API 接口。该服务器使 AI 助手能够通过 Hevy API（需要 PRO 订阅）访问和管理锻炼数据、训练计划、锻炼模板等。

功能

• 锻炼管理: 获取、创建和更新锻炼
• 训练计划管理: 访问和管理训练计划
• 锻炼模板: 浏览可用的锻炼模板
• 文件夹组织: 管理训练计划文件夹

前提条件

• Node.js (v20 或更高版本)
• npm 或 yarn
• 一个 Hevy API 密钥

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 hevy-mcp：

npx -y @smithery/cli install @chrisdoc/hevy-mcp --client claude

手动安装

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

# 安装依赖
npm install

# 从示例创建 .env 文件
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": "your-api-key-here"
    }
  }
}

请确保将 your-api-key-here 替换为您实际的 Hevy API 密钥。

配置

在项目根目录中创建一个 .env 文件，内容如下：

HEVY_API_KEY=your_hevy_api_key_here

将 your_hevy_api_key_here 替换为您实际的 Hevy API 密钥。

用法

开发

npm run dev

这将在开发模式下启动 MCP 服务器，并启用热重载。

生产

npm run build
npm start

可用的 MCP 工具

该服务器实现了以下 MCP 工具：

锻炼工具

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

训练计划工具

• get-routines: 获取并格式化训练计划数据
• create-routine: 创建新的训练计划
• update-routine: 更新现有的训练计划
• get-routine: 通过 ID 获取单个训练计划

锻炼模板工具

• get-exercise-templates: 获取锻炼模板
• get-exercise-template: 通过 ID 获取模板

训练计划文件夹工具

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

项目结构

hevy-mcp/
├── .env                   # 环境变量 (API 密钥)
├── src/
│   ├── index.ts           # 主入口点
│   ├── tools/             # MCP 工具实现目录
│   │   ├── workouts.ts    # 与锻炼相关的工具
│   │   ├── routines.ts    # 与训练计划相关的工具
│   │   ├── templates.ts   # 锻炼模板工具
│   │   └── folders.ts     # 训练计划文件夹工具
│   ├── generated/         # API 客户端 (生成的代码)
│   │   ├── client/        # Kiota 生成的客户端
│   └── utils/             # 辅助工具
│       ├── formatters.ts  # 数据格式化助手
│       └── validators.ts  # 输入验证助手
├── scripts/               # 构建和实用程序脚本
└── tests/                 # 测试套件

开发

代码风格

本项目使用 Biome 进行代码格式化和 linting：

npm run check

生成 API 客户端

API 客户端是使用 Kiota 从 OpenAPI 规范生成的：

npm run export-specs
npm run build:client

许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

致谢

• Model Context Protocol 用于 MCP SDK
• Hevy 用于他们的健身追踪平台和 API