Analyze progress, plan routines, discover exercises, and safely log training in Hevy.
Important
This is an unofficial community integration maintained by Liam O'Grady. It is not affiliated with, endorsed by, or maintained by Hevy.
| Understand your training | Plan what comes next | Keep writes safe |
|---|---|---|
| Summarize recent activity, volume, consistency, exercise history, and body-measurement trends. | Search Hevy's exercise catalog and build routines around your goals, schedule, equipment, and constraints. | Preview every create or update, require confirmation, and never invent completed sets or timestamps. |
The plugin exposes the complete read/write tool set provided by
hevy-mcp, including workouts,
routines, folders, exercise templates, exercise history, body measurements,
and account details.
The examples below use entirely synthetic data.
| Training analysis | Write confirmation |
|---|---|
 |
 |
flowchart LR
U["You"] --> C["ChatGPT or Codex"]
C --> P["Hevy for ChatGPT"]
P --> O["OAuth bridge"]
O --> M["hevy-mcp"]
M --> H["Hevy API"]
style P fill:#45E58F,color:#08110C,stroke:#45E58F
style O fill:#17251E,color:#F4FFF8,stroke:#45E58F
style M fill:#17251E,color:#F4FFF8,stroke:#45E58F
The repository contains no Hevy credential. During connection, the hosted OAuth bridge asks for a Hevy PRO API key once and issues ChatGPT or Codex an OAuth grant. Enter the key only on that authorization page—never in a prompt, configuration file, URL, screenshot, issue, or commit.
- A Hevy account with Hevy PRO API access
- ChatGPT developer mode for a custom ChatGPT app, or Codex with plugin support
- Access to the third-party hosted MCP endpoint at
https://mcp.hevy-mcp.dev/mcp
Add this repository as a Git marketplace, then install the plugin:
codex plugin marketplace add ogradyliam5/hevy-chatgpt-plugin --ref main
codex plugin add hevy@ogradyliam5Start a new Codex task so the new skill and MCP tools are loaded. When prompted, choose Connect, enter the Hevy API key on the hosted OAuth page, and approve the connection.
- Open Settings → Plugins and enable developer mode.
- Create an app using
https://mcp.hevy-mcp.dev/mcp. - Choose OAuth authentication and acknowledge the custom-connector notice.
- Select Sign in with Hevy, enter the Hevy PRO API key on the hosted OAuth page, and approve access.
The included .app.json points to the development app used for this prototype.
Development apps can be account-scoped; another ChatGPT account may need to
register its own app and replace the app ID locally. This repository is not a
public ChatGPT directory submission.
Analyze my training over the last four weeks and show the evidence.
Find my push routine and explain how its weekly volume is distributed.
Build a four-day routine for my goals and equipment. Show me the full plan
before saving anything.
Log today's workout from my saved routine. Ask for every missing completed-set
result and timestamp before writing.
| Situation | Plugin behavior |
|---|---|
| Read-only questions | Uses narrow date ranges and page sizes, fetching more only when needed. |
| Creates and updates | Shows the exact intended change and asks for explicit confirmation. |
| Completed workouts | Never invents weights, reps, duration, RPE, completion state, or timestamps. |
| Uncertain create result | Reads back the relevant resource instead of retrying and risking a duplicate. |
| Routine or workout update | Fetches the current object first because updates are full replacements. |
| Deletion request | Explains that the Hevy API does not expose supported delete tools. |
| Authentication error | Reports a sanitized error and never asks for a credential in chat. |
The Hevy tools are not available
Start a new ChatGPT conversation or Codex task after installing. Confirm that
the hevy plugin is enabled and that the remote marketplace has been added.
OAuth linking fails
Confirm that the API key is active and belongs to a Hevy PRO account. Reconnect from the plugin settings. Do not paste the key into chat or store it in this repository.
A write timed out
Do not retry automatically. First ask the plugin to read the relevant workout, routine, folder, exercise, or measurement to determine whether the original request succeeded.
I want to delete something
Deletion is not exposed by the connected Hevy tools. The plugin will not simulate deletion by overwriting or emptying another resource.
.agents/plugins/marketplace.json Portable Codex marketplace
plugins/hevy/ Plugin manifest, app, MCP, skill, and assets
docs/ Original README branding and mockup sources
Validate the plugin and its skill using the validators bundled with Codex:
python <plugin-creator>/scripts/validate_plugin.py plugins/hevy
python <skill-creator>/scripts/quick_validate.py plugins/hevy/skills/hevy-trainingBefore publishing a change, also verify all referenced assets exist and scan the full Git history for secrets or personal workout data.
Please read SECURITY.md and use GitHub's private vulnerability reporting flow. Never open a public issue containing credentials or personal training information.
- Hevy for the fitness platform and public API
- chrisdoc/hevy-mcp for the MIT-licensed MCP server and hosted OAuth bridge
- Model Context Protocol for the integration standard
MIT © 2026 Liam O'Grady
Hevy and related marks belong to their respective owner. The original community mark and documentation artwork in this repository are not official Hevy assets.