Hevy MCP
hevy-mcp: Hevy Fitness API 用モデルコンテキストプロトコルサーバー
HevyフィットネストラッキングアプリとそのAPIと連携するモデルコンテキストプロトコル(MCP)サーバー実装。このサーバーにより、AIアシスタントはHevy API(PROサブスクリプションが必要)を介してワークアウトデータ、ルーチン、エクササイズテンプレートなどにアクセスし、管理できるようになります。
特徴
ワークアウト管理: ワークアウトの取得、作成、更新
ルーチン管理: トレーニングルーチンにアクセスして管理する
エクササイズテンプレート: 利用可能なエクササイズテンプレートを参照します
フォルダの整理: 日常的なフォルダを管理する
Related MCP server: hevy-mcp
前提条件
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カーソルとの統合
この 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_hereyour_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 checkAPIクライアントの生成
API クライアントは、Kiota を使用して OpenAPI 仕様から生成されます。
npm run export-specs
npm run build:clientライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。
貢献
貢献を歓迎します!お気軽にプルリクエストを送信してください。
謝辞
MCP SDK のモデルコンテキストプロトコル
HevyのフィットネストラッキングプラットフォームとAPI
Available Tools
23 toolscreate-body-measurementA
Create a body measurement entry for a given date. All measurement fields are optional; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Returns 409 if an entry already exists for that date — use update-body-measurement instead.
Inputs: date (required), hips, waist, neckCm, +14 more.
create-exercise-templateB
Create a custom exercise template with title, type, equipment, and muscle groups.
Inputs: title (required), muscleGroup (required), exerciseType (required), equipmentCategory (required), +1 more.
create-routineA
Create a new workout routine in your Hevy account. Requires a title and at least one exercise with sets. Optionally assign to a folder. Returns the full routine details including the new routine ID.
Inputs: title (required), notes, folderId, exercises.
create-routine-folderA
Create a new routine folder in your Hevy account. Requires a name for the folder. Returns the full folder details including the new folder ID.
Inputs: name (required).
create-workoutA
Create a new workout in your Hevy account. Requires title, start/end times, and at least one exercise with sets. Returns the complete workout details upon successful creation including the newly assigned workout ID.
Inputs: title (required), endTime (required), startTime (required), exercises, +2 more.
get-body-measurementARead-only
Get a single body measurement by date. Returns all measurement fields for the specified date.
Inputs: date (required). Returns: bodyMeasurement
get-body-measurementsBRead-only
Get a paginated list of body measurements for the authenticated user. Returns measurements including weight, body fat, and various circumference measurements.
Inputs: page, pageSize. Returns: bodyMeasurements
get-exercise-historyARead-only
Get past sets for a specific exercise template, optionally filtered by start and end dates.
Inputs: exerciseTemplateId (required), endDate, startDate. Returns: exerciseHistory
get-exercise-templateARead-only
Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.
Inputs: exerciseTemplateId (required). Returns: exerciseTemplate
get-exercise-templatesARead-only
Get a paginated list of exercise templates (default and custom) with details like name, category, equipment, and muscle groups. Useful for browsing or searching available exercises.
Inputs: page, pageSize. Returns: exerciseTemplates
get-routineARead-only
Get a routine by its ID using the direct endpoint. Returns all details for the specified routine.
Inputs: routineId (required). Returns: routine
get-routine-folderARead-only
Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.
Inputs: folderId (required). Returns: routineFolder
get-routine-foldersARead-only
Get a paginated list of your routine folders, including both default and custom folders. Useful for organizing and browsing your workout routines.
Inputs: page, pageSize. Returns: routineFolders
get-routinesARead-only
Get a paginated list of your workout routines, including custom and default routines. Useful for browsing or searching your available routines.
Inputs: page, pageSize. Returns: routines
get-user-infoARead-only
Get the authenticated user's account info, including user ID, display name, and public profile URL. Useful for verifying which account the API key belongs to.
Inputs: no named parameters. Returns: user
get-workoutARead-only
Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.
Inputs: workoutId (required). Returns: workout
get-workout-countARead-only
Get the total number of workouts on the account. Useful for pagination or statistics.
Inputs: no named parameters. Returns: count
get-workout-eventsARead-only
Retrieve a paged list of workout events (updates or deletes) since a given date. Events are ordered from newest to oldest. The intention is to allow clients to keep their local cache of workouts up to date without having to fetch the entire list of workouts.
Inputs: page, since, pageSize. Returns: events
get-workoutsARead-only
Get a paginated list of workouts. Returns workout details including title, description, start/end times, and exercises performed. Results are ordered from newest to oldest.
Inputs: page, pageSize. Returns: workouts
search-exercise-templatesARead-only
Search exercise templates by name with optional muscle group filter. Fetches all templates from the Hevy API on first call, caches the catalog in memory with a bounded TTL cache, and reuses it for subsequent searches. Use refresh:true to force a re-fetch.
Inputs: query (required), refresh, primaryMuscleGroup. Returns: exerciseTemplates
update-body-measurementADestructiveIdempotent
Update an existing body measurement entry for a given date. Only the fields you provide are sent and updated; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Requires at least one measurement field. Returns 404 if no entry exists for the date.
Inputs: date (required), hips, waist, neckCm, +14 more.
update-routineADestructiveIdempotent
Update an existing routine by ID. You can modify the title, notes, and exercise configurations. Returns the updated routine with all changes applied.
Inputs: title (required), routineId (required), notes, exercises.
update-workoutADestructiveIdempotent
Update an existing workout by ID. You can modify the title, description, start/end times, privacy setting, and exercise data. Returns the updated workout with all changes applied.
Inputs: title (required), endTime (required), startTime (required), workoutId (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Every tool has a distinct purpose and clear naming: singular vs plural separates detail views from list views, and each resource type has its own verb-noun pair. Even similar tools like get-exercise-templates and search-exercise-templates are distinguishable by their retrieval mode.
Tool names consistently follow a verb-noun pattern (get, create, update, search) with snake_case and predictable singular/plural distinctions. The naming is uniform across workouts, routines, folders, exercise templates, and body measurements.
23 tools is on the heavy side, but the count is structured across several coherent subdomains (workouts, routines, templates, measurements). It feels somewhat large but not bloated or redundant.
The set covers read and create/update operations broadly, but there are no delete operations for any resource type, and exercise templates lack update/delete. Those are significant lifecycle gaps for a CRUD-oriented API, likely causing agent failures when cleanup or correction is needed.
Maintenance
Related MCP Connectors
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that connects AI clients to the Hevy workout tracking app, allowing users to manage routines and exercises. It enables reading workout history and logging new fitness sessions through simple natural language commands.-
- AlicenseNot gradedqualityDmaintenancePython MCP server for the Hevy fitness app. Gives Claude full access to your Hevy data. Log workouts, manage routines, track body measurements, browse exercises, and more. Covers all 25 endpoints of the official Hevy API.MIT
- AlicenseAqualityCmaintenanceAn MCP server that interfaces with the Hevy fitness tracking API, enabling AI assistants to manage workouts, routines, exercise templates, and more via natural language.26MIT
- AlicenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol (MCP) server that provides AI assistants with access to the Hevy fitness tracking API. This allows you to log workouts, manage routines, browse exercises, and track your fitness progress directly through AI chat interfaces.13 npmMIT