AI导哈

健身数据查询服务器

一个提供健身数据访问的模型上下文协议（MCP）服务器，支持通过自然语言查询锻炼历史、运动详情和训练计划。

  • by Caiuse
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Caiuse/hevy-mcp

使用说明

Hewy MCP服务器

模型上下文协议（MCP）服务器，提供从 Hevy 健身跟踪应用程序。该服务器使人工智能助手能够通过自然语言对话查询锻炼历史、锻炼细节、例程和其他健身数据。

特性

  • 锻炼历史记录：检索带有详细锻炼和设置信息的分页锻炼历史记录
  • 练习模板：访问运动定义，包括肌肉群和运动类型
  • 运动历史：使用可选的日期过滤功能跟踪特定练习随时间的进度
  • 锻炼计划：查看和分析计划的锻炼计划
  • 全面的错误处理：清晰的错误消息和强大的API错误处理
  • 异步操作：内置async/await以实现高效的I/O操作
  • 多种运输方式：支持stdio和HTTP/SSE（服务器发送事件）
  • 测试模式：内置模拟数据模式，用于在没有真正API密钥的情况下进行测试

安装

使用uvx（推荐）

使用此MCP服务器的最简单方法是 uvx:

uvx hevy-mcp-server

使用pip

pip install hevy-mcp-server

开发安装

克隆存储库并在开发模式下安装：

git clone <repository-url>
cd hevy-mcp-server
pip install -e ".[dev]"

配置

获取Hevy API密钥

  1. 访问 https://hevyapp.com/api-key
  2. 使用您的Hevy帐户登录
  3. 生成API密钥（UUID格式）
  4. 复制API密钥以便在配置中使用

环境变量

创建一个 .env 文件或设置环境变量：

# Required
HEVY_API_KEY=your_api_key_here

# Optional (with defaults)
HEVY_API_BASE_URL=https://api.hevyapp.com
HEVY_REQUEST_TIMEOUT=30
LOG_LEVEL=INFO

看 .env.example 获取完整的配置模板。

测试模式

对于没有真正API密钥的测试，请使用 TEST_KEY 值：

export HEVY_API_KEY="TEST_KEY"

这启用了模拟数据模式，该模式返回真实的测试数据，而不进行实际的API调用。看 README_TEST_MODE.md 了解详情。

MCP客户端配置

选项1:stdio模式（默认）

将服务器添加到MCP客户端配置中（例如。， .kiro/settings/mcp.json):

{
  "mcpServers": {
    "hevy": {
      "command": "uvx",
      "args": ["hevy-mcp-server"],
      "env": {
        "HEVY_API_KEY": "your_api_key_here"
      }
    }
  }
}

对于当地发展：

{
  "mcpServers": {
    "hevy": {
      "command": "python",
      "args": ["-m", "hevy_mcp.server"],
      "cwd": "/path/to/hevy-mcp-server",
      "env": {
        "HEVY_API_KEY": "your_api_key_here"
      }
    }
  }
}

选项2:HTTP/SSE模式（服务器）

启动HTTP服务器：

# Start with TEST_KEY (mock data)
python start_http_server.py

# Or with real API key
export HEVY_API_KEY="your_api_key"
python start_http_server.py --port 8000

然后配置您的MCP客户端以连接到HTTP端点：

{
  "mcpServers": {
    "hevy-http": {
      "url": "http://127.0.0.1:8000/sse",
      "transport": "sse"
    }
  }
}

看 HTTP_SERVER_GUIDE.md 获取详细的HTTP服务器文档。

可用工具

服务器提供以下MCP工具：

1.获取_工作_历史

检索分页的锻炼历史记录。

参数：

  • page （可选，默认值：1）：页码
  • page_size （可选，默认值：10，最大值：10）：每页训练次数

例子：

Get my last 5 workouts

2.获取工作详情

获取特定锻炼的详细信息。

参数：

  • workout_id （必填）：训练ID

例子：

Show me details for workout abc123

3.获取工作计数

获取帐户上的锻炼总数。

例子：

How many workouts have I logged?

4.get_exercise_templates

检索分页的练习模板列表。

参数：

  • page （可选，默认值：1）：页码
  • page_size （可选，默认值：100，最大值：100）：每页模板数

例子：

Show me available exercises

5.get_exercise_template_details

获取特定练习模板的详细信息。

参数：

  • exercise_template_id （必填）：练习模板ID

例子：

What muscles does exercise xyz789 work?

6.锻炼历史

获取特定锻炼模板的锻炼历史记录。

参数：

  • exercise_template_id （必填）：练习模板ID
  • start_date （可选）：ISO 8601格式的开始日期（例如，2025-01-01）
  • end_date （可选）：ISO 8601格式的结束日期

例子：

Show my bench press progress over the last month

7.get_routines

检索训练例程的分页列表。

参数：

  • page （可选，默认值：1）：页码
  • page_size （可选，默认值：10，最大值：10）：每页例程数

例子：

What workout routines do I have?

8.get_routine_details

获取特定例程的详细信息。

参数：

  • routine_id （必填）：例程ID

例子：

Show me the details of my push day routine

使用示例

在MCP客户端中配置后，您可以使用自然语言与Hewy数据交互：

  • “显示我上周的锻炼记录”
  • “什么运动是针对胸部的？”
  • “在过去的3个月里，我的下蹲重量是如何增加的？”
  • “我的腿部日常活动是什么？”
  • “我总共完成了多少次锻炼？”

发展

运行测试

pytest

在本地运行服务器

python -m hevy_mcp.server

错误处理

服务器为常见问题提供明确的错误消息：

  • 身份验证错误：API密钥无效或丢失
  • 未发现错误：无效的锻炼/锻炼/例行ID
  • 验证错误：参数或日期格式无效
  • 网络错误：Hevy API的连接问题
  • 速率限制：超过API费率限制

需求

  • Python 3.10或更高版本
  • 有效的Hevy API密钥
  • 互联网连接以访问Hevy API

许可证

[在此处添加您的许可证]

贡献

[在此处添加贡献指南]

支持

关于以下问题：

  • 此MCP服务器：[添加问题跟踪链接]
  • 赫维API：请通过以下方式联系Hewy支持https://hevyapp.com/support
  • MCP协议：参观https://modelcontextprotocol.io

致谢

内置 FastMCP 并由 赫维API.

相关 MCP