项目简介

hevy-mcp 是一个基于 Model Context Protocol (MCP) 构建的服务器，它充当 AI 助手和 Hevy 健身应用 API 之间的桥梁。通过此服务器，AI 助手可以安全、便捷地访问用户的 Hevy 健身数据，例如：

获取和管理健身记录 (Workouts)
获取和管理健身计划 (Routines)
浏览健身动作模板 (Exercise Templates)
管理健身计划文件夹 (Routine Folders)

这使得 AI 助手能够理解用户的健身习惯和偏好，从而提供更加个性化和智能的健身指导与支持。

主要功能点

健身记录管理：
- 获取健身记录列表及详细信息
- 创建和更新健身记录
- 获取健身记录更新事件，保持数据同步
健身计划管理：
- 获取健身计划列表及详细信息
- 创建和更新健身计划
健身动作模板：
- 获取健身动作模板列表及详细信息
健身计划文件夹管理：
- 获取健身计划文件夹列表及详细信息
- 创建健身计划文件夹

安装步骤

克隆仓库

git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

安装依赖
```
npm install
```

配置环境变量

复制 '.env.sample' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入你的 Hevy API 密钥。注意：你需要 Hevy PRO 订阅才能使用 API。

cp .env.sample .env
# 编辑 .env 文件，添加 HEVY_API_KEY=你的API密钥

服务器配置

要将此 MCP 服务器与 MCP 客户端（例如 Cursor 编辑器）集成，你需要配置客户端的 MCP 设置。以下是 Cursor 编辑器的 'mcp.json' 配置文件示例：

{
  "hevy-mcp-server": {  //  服务器名称，可以自定义
    "command": "npx",  //  启动命令，这里使用 npx
    "args": ["-y", "hevy-mcp"], // 启动参数，-y 表示自动确认， hevy-mcp 是包名
    "env": {  //  环境变量
      "HEVY_API_KEY": "你的API密钥" //  Hevy API 密钥，请替换为你的实际密钥，也可以在 .env 文件中配置
    }
  }
}

配置说明：

'"hevy-mcp-server"': 服务器的名称，你可以自定义，用于在 Cursor 中标识此服务器。
'"command": "npx"': 指定用于启动服务器的命令。'npx' 允许你直接运行本地安装的 npm 包的可执行文件。
'"args": ["-y", "hevy-mcp"]': 传递给 'npx' 的参数。
- '"-y"': 'npx -y' 参数表示自动确认执行 npm 包，避免在安装过程中出现交互式提示。
- '"hevy-mcp"': 指定要执行的 npm 包名称，这里对应 'package.json' 中的 'name' 字段。当执行 'npx hevy-mcp' 时，实际上会运行 'node dist/index.js' (根据 'tsup.config.ts' 中的配置，tsup 打包后输出目录为 dist)。
'"env"': 配置环境变量。
- '"HEVY_API_KEY": "你的API密钥"': 设置 'HEVY_API_KEY' 环境变量，用于服务器访问 Hevy API。请务必替换 '"你的API密钥"' 为你实际的 Hevy API 密钥。 建议将 API 密钥配置在 '.env' 文件中，而不是直接写在 'mcp.json' 里，以提高安全性。如果在 '.env' 文件中配置了 'HEVY_API_KEY'，这里可以省略 '"env"' 部分，服务器会自动从 '.env' 文件中读取。

Cursor 'mcp.json' 文件路径：

macOS: '~/.cursor/mcp.json'
Linux: '~/.cursor/mcp.json'
Windows: '%USERPROFILE%.cursor\mcp.json'

如果 'mcp.json' 文件不存在，请手动创建。

基本使用方法

启动服务器

在项目根目录下，根据需要选择开发模式或生产模式启动服务器：
- 开发模式 (热重载)
```
npm run dev
```
- 生产模式
```
npm run build
npm start
```
启动成功后，服务器将通过 Stdio (标准输入输出) 与 MCP 客户端通信。
在 MCP 客户端中使用

在配置好 MCP 客户端后，客户端应该能够检测到并连接到 'hevy-mcp-server'。你可以在客户端中调用此服务器提供的工具，例如在 Cursor 编辑器中，你可以使用 '@tool get-workouts' 来获取健身记录列表。

注意： 此服务器提供的工具都需要 Hevy API 密钥才能正常工作。请确保你已正确配置 API 密钥，并且你的 Hevy 账户拥有 PRO 订阅。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息