hevy-mcp: 用于 Hevy 健身 API 的 Model Context Protocol 服务器

这是一个 Model Context Protocol (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

手动安装

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies
npm install

# Create .env file from sample
cp .env.sample .env
# Edit .env and add your Hevy API key

与 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                   # Environment variables (API keys)
├── src/
│   ├── index.ts           # Main entry point
│   ├── tools/             # Directory for MCP tool implementations
│   │   ├── workouts.ts    # Workout-related tools
│   │   ├── routines.ts    # Routine-related tools
│   │   ├── templates.ts   # Exercise template tools
│   │   └── folders.ts     # Routine folder tools
│   ├── generated/         # API client (generated code)
│   │   ├── client/        # Kiota-generated client
│   └── utils/             # Helper utilities
│       ├── formatters.ts  # Data formatting helpers
│       └── validators.ts  # Input validation helpers
├── scripts/               # Build and utility scripts
└── tests/                 # Test suite

开发

代码风格

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

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