Best for
- Hevy PRO users
- Fitness enthusiasts who want AI-assisted training analysis and planning
- Developers who want to integrate Hevy data into MCP clients like Claude Desktop, Codex, Cursor
H
Hevy MCP Server
Community
Manage workouts, routines, and exercise data through the Hevy API
GitHub source repository ↗
66FMRS · C
Hevy MCP Server is a feature-rich MCP server providing 26 tools to manage Hevy data, supporting both local stdio and hosted Streamable HTTP modes. It is ideal for advanced users who want AI-assisted training analysis, but requires a Hevy PRO subscription and is not an official product. Security considerations include API key protection and telemetry privacy.
Hevy MCP Server is an open-source Model Context Protocol (MCP) server for the Hevy fitness and workout tracking app. It allows AI assistants to read, analyze, create, and update your Hevy workouts, routines, exercise templates, and body measurements through authenticated Hevy API requests. It supports multi-step workflows, guided prompts, and a wide range of tools for training analysis, exercise search, and planning.
Tools
get-training-summary
Summarize 1-12 weeks of workout activity and body-measurement trends in one call.
get-workouts
List workouts from newest to oldest with exercise and timing details.
get-workout
Get complete details for one workout by ID.
get-workout-count
Return the account's total workout count.
get-workout-events
List workout update and delete events since a timestamp.
create-workout
Create a completed workout in Hevy.
update-workout
Patch workout metadata by ID; omitted fields and all exercises remain unchanged.
replace-workout-exercises
Replace all exercises and sets while preserving workout metadata.
search-routines
Search routine titles and return compact metadata for discovery.
get-routines
List custom and default workout routines.
get-routine
Get one routine and its exercise configuration by ID.
create-routine
Create a reusable workout routine.
update-routine
Replace an existing routine's content.
get-routine-folders
List default and custom routine folders.
get-routine-folder
Get one routine folder's metadata by ID.
create-routine-folder
Create a routine folder.
get-exercise-templates
List exercise templates with equipment and muscle metadata.
get-exercise-template
Get complete metadata for one exercise template by ID.
search-exercise-templates
Search the full exercise catalog by title substring.
create-exercise-template
Create a custom exercise template.
get-exercise-history
Get past performed sets for one exercise template.
get-body-measurements
List dated body measurements.
get-body-measurement
Get the body measurement entry for one date.
create-body-measurement
Create a dated body measurement.
update-body-measurement
Update the body measurement for an existing date.
get-user-info
Return the user's ID, display name, and public profile URL.
Setup
- Create an API key in Hevy (requires Hevy PRO).
- For local install, add
npx -y hevy-mcpto your MCP client config with environment variableHEVY_API_KEY. - For hosted endpoint, use
https://mcp.hevy-mcp.dev/mcpas Streamable HTTP URL withAuthorization: Bearer <HEVY_API_KEY>header. - Restart or reconnect the client and ask your first question.
claude_desktop_config.json
{
"mcpServers": {
"hevy": {
"command": "npx",
"args": [
"-y",
"hevy-mcp"
],
"env": {
"HEVY_API_KEY": "your-hevy-api-key"
}
}
}
}
Fit and risk
Not for
- Users without Hevy PRO subscription
- Users who need deletion capabilities (Hevy API does not expose delete endpoints)
- Users looking for official support (this is community-maintained, not affiliated with Hevy)
Required permissions
- Requires Hevy API key (`HEVY_API_KEY`)
- Can read and write Hevy data (workouts, routines, exercise templates, body measurements, etc.)
- Hosted endpoint validates the API key with Hevy on each request and forwards it as `api-key` header
Risks and side effects
- API key leakage risk: never put key in source control, URLs, logs, or screenshots.
- Mutation risk: create operations may produce duplicates on retry; update operations replace existing records.
- Privacy: local package enables telemetry by default (can be disabled), sending errors and metrics to external services.
- Dependency on third-party service: hosted endpoint relies on Cloudflare Worker, availability may vary.
- Tool confirmation: mutation tools may require client confirmation, but support varies by client.
Troubleshooting
- If server doesn't appear, restart or reconnect your MCP client after config changes.
- If `npx` fails, ensure Node.js 20 or newer and run `npx -y hevy-mcp --version`.
- If Codex can't see server, run `codex mcp list` and start a new session after confirming 'hevy' entry.
- If hosted auth fails, confirm key is active, belongs to Hevy PRO account, and is sent as `Authorization: Bearer <HEVY_API_KEY>`.
- For diagnostics, set `HEVY_MCP_DEBUG=1`; output goes to stderr and doesn't interfere with MCP.
- If local auth fails, confirm key is active and available to child process as `HEVY_API_KEY`.
Use cases
Analyze training progress over recent weeks, frequency, exercise distribution, and body measurement trends.
Query recent workouts, frequently trained exercises, routine details, or exercise history in natural language.
Create or update workouts, routines, folders, custom exercises, and body measurements.
Search exercise templates and routines with compact, AI-friendly results.
Supported clients
Claude DesktopFull support
CodexFull support
CursorFull support
Google AntigravityFull support