Hevy MCP

by chrisdoc

310 stars

1.1k downloads

Not rated

GitHub

Other

About

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

Details

Author: chrisdoc
GitHub stars: 310
Downloads: 1,108
Categories: Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Hevy MCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

From the repository

—

`get-workouts`

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.

`get-workout`

Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.

`get-workout-count`

Get the total number of workouts on the account. Useful for pagination or statistics.

`get-workout-events`

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.

`create-workout`

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.

`update-workout`

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.

`get-routines`

Get a paginated list of routines. Returns routine details including title, creation date, folder assignment, and exercise configurations. Results include both default and custom routines.

`get-routine`

Get complete details of a specific routine by ID. Returns all routine information including title, notes, assigned folder, and detailed exercise data with set configurations.

`create-routine`

Create a new workout routine in your Hevy account. Requires title and at least one exercise with sets. Optionally assign to a specific folder. Returns the complete routine details upon successful creation including the newly assigned routine ID.

`update-routine`

Update an existing workout routine by ID. You can modify the title, notes, and exercise data. Returns the updated routine with all changes applied. Note that you cannot change the folder assignment through this method.

`get-exercise-templates`

Get a paginated list of exercise templates available on the account. Returns both default and custom exercise templates with details including title, type, primary muscle group, and secondary muscle groups. Supports up to 100 templates per page.

`get-exercise-template`

Get complete details of a specific exercise template by ID. Returns all template information including title, type, primary muscle group, secondary muscle groups, and whether it's a custom exercise.

`get-routine-folders`

Get a paginated list of routine folders available on the account. Returns folder details including ID, title, index (order position), and creation/update timestamps. Useful for organizing routines into categories.

`get-routine-folder`

Get complete details of a specific routine folder by ID. Returns all folder information including title, index (order position), and creation/update timestamps.

`create-routine-folder`

Create a new routine folder in your Hevy account. The folder will be created at index 0, and all other folders will have their indexes incremented. Returns the complete folder details upon successful creation including the newly assigned folder ID.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "hevy mcp": {
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "hevy-mcp"
                ],
                "env": {
                    "HEVY_API_KEY": "{HEVY_API_KEY}"
                }
            }
        }
    }
}

McpServers

{
    "filesystem": {
        "command": "npx",
        "args": [
            "-y",
            "hevy-mcp"
        ],
        "env": {
            "HEVY_API_KEY": "{HEVY_API_KEY}"
        }
    }
}

Connect to the hosted MCP·Use the Hevy CLI·Watch the 18-second demo·Explore all 22 tools

Prefer the terminal? The separate @chrisdoc/hevy-clipackage reads workouts, routines, exercises, and body measurements directly from the Hevy API, and can create or update those resources with explicit confirmation. Deletion is not supported.

npm install -g @chrisdoc/hevy-cli export HEVY_API_KEY=your-hevy-api-key hevy workouts list --page-size 10 hevy summary --weeks 4

Add--jsonto any command for scripts and pipelines. The CLI is a standalone Hevy API client, not an MCP wrapper. See packages/cli/README.mdfor the full command reference, pagination behavior, and exit codes.

hevy-mcpis an open-source Model Context Protocol (MCP)server for the Hevyfitness and workout tracking app. It lets AI assistants read, analyze, create, and update your Hevy workouts, routines, exercise templates, and body measurements through authenticated Hevy API requests.

The repository is organized as a private workspace with explicit runtime boundaries:@hevy-mcp/hevy-clientowns the web-safe Hevy client,@hevy-mcp/coreowns MCP tools and server construction,hevy-mcpis the published Node.js stdio adapter, and@hevy-mcp/workeris the private Cloudflare HTTP/OAuth adapter. Only the Node workspace is publishable.

A Hevy API key, available withHevy PRO, is required.

Click the preview to play the full-quality 18-second demo.

In the demo, the assistant retrieves real Hevy data and answers a multi-part training question with evidence from the user's workout history.

- Analyze training progress:summarize 1-12 weeks of workouts and body measurements in one tool call.
- Ask questions in plain language:find recent sessions, frequently trained exercises, consistency gaps, routine details, or exercise history.
- Plan and log training:create or update workouts, routines, routine folders, custom exercises, and body measurements.
- Search without huge responses:discover routines and exercise templates with compact, AI-friendly results.
- Connect from your preferred MCP client:use the hosted Streamable HTTP endpoint or run locally with Codex, Claude Desktop, Cursor, and other clients.
- Start without installing anything:connect directly to the production Cloudflare Worker—no Node.js, package download, or Docker container required.
- Keep local control when you want it:run the same server withnpx,bunx, or the official Docker image.

Analyze my training over the last six weeks. Show workouts per week, my most frequently trained exercises, any obvious gaps or inconsistencies, and cite the workout evidence you used.

Find my push-day routine and show its exercises and sets.

Compare my recent body measurements with my training consistency.

Create a completed workout from my saved routine. Ask me for any missing set results before writing it to Hevy.

The repository includes a Claude plugin that connects to the hosted OAuth-enabled MCP endpoint without embedding a user's Hevy API key.

In Claude, openSettings → Connectors → Add custom connectorand enter:

Complete the OAuth flow and enter the Hevy API key when prompted. The same remote endpoint can be used by Claude Desktop and other clients that support remote MCP connectors.

The Claude plugin is defined by .claude-plugin/plugin.jsonand .mcp.json. Install it from this public repository or from the Claude Plugin Directory after publication. It adds the hosted Hevy MCP connector and the Hevy workout skill.

See the privacy policyfor the hosted service's data handling details.

Create an API key in Hevy's API settings, then keep it somewhere secure. API access currently requires a Hevy PRO subscription.

The hosted Cloudflare endpoint is the fastest way to start. It runs remotely, so your client does not need Node.js, Bun, Docker, or a local server process.

The endpoint uses Streamable HTTP. Send your Hevy API key as a bearer token on every request.

Codex CLI, the Codex desktop app, and the IDE extension share the same MCP configuration. Make your Hevy API key available in the environment that starts Codex, then add the hosted server:

export HEVY_API_KEY=your-hevy-api-key codex mcp add hevy \ --url https://mcp.hevy-mcp.dev/mcp \ --bearer-token-env-var HEVY_API_KEY

Codex stores the environment variable name, not the key itself, in its MCP configuration. Restart Codex or begin a new session, then runcodex mcp listto verify the server is configured.

Clients that accept a remote MCP URL and fixed headers commonly use this shape:

{ "mcpServers": { "hevy": { "url": "https://mcp.hevy-mcp.dev/mcp", "headers": { "Authorization": "Bearer your-hevy-api-key" } } } }

Exact configuration keys vary by client. The hosted server requires support for Streamable HTTP and a fixedAuthorizationheader.

[!IMPORTANT] Treat the bearer value like a password. The Worker validates it with Hevy for each request, does not store it, and forwards it to Hevy only as the requiredapi-keyheader.

Choose local stdio if you prefer to run the server on your own machine or your client cannot attach a fixed authorization header to remote MCP requests.

codex mcp add hevy \ --env HEVY_API_KEY=your-hevy-api-key \ -- npx -y hevy-mcp

Add thismcpServersentry to your client configuration:

{ "mcpServers": { "hevy": { "command": "npx", "args": ["-y", "hevy-mcp"], "env": { "HEVY_API_KEY": "your-hevy-api-key" } } } }

There are two ways to configure the Hevy MCP server for Google Antigravity (agy):

This utilizes the built-in plugin system:

agy plugin install https://github.com/chrisdoc/hevy-mcp

Provide theHEVY_API_KEYin your host shell environment so the CLI child process can inherit it:

- Persistent:Save the environment variableHEVY_API_KEYin your system/shell configurations:

- macOS / Linux:Add it to your shell profile configurations (e.g.,~/.zshrcor~/.bashrc):

export HEVY_API_KEY="your-actual-api-key"

[Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")

export HEVY_API_KEY="your-actual-api-key"

If you prefer configuring it statically via the global configuration file:
-

Open your global MCP configuration file:

- Location:~/.gemini/config/mcp_config.json

Add thehevyconfiguration block under themcpServerskey. Make sure to merge this entry with any existing servers you have configured rather than replacing the entire file contents:

{ "mcpServers": { "hevy": { "command": "npx", "args": ["-y", "hevy-mcp"], "env": { "HEVY_API_KEY": "your-actual-api-key" } } } }

- Claude Desktop on macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Claude Desktop on Windows:%APPDATA%\Claude\claude_desktop_config.json
- Cursor:~/.cursor/mcp.json

Restart or reconnect the client after saving the file.

Configure your client to launch this command withHEVY_API_KEYin the child process environment:

npxrequires Node.js 20 or newer. Restart or reconnect your client after saving its configuration.

{ "mcpServers": { "hevy": { "command": "bunx", "args": ["hevy-mcp@latest"], "env": { "HEVY_API_KEY": "your-hevy-api-key" } } } }

Official images supportlinux/amd64andlinux/arm64. Keep stdin open with-ibecause the container runs the stdio MCP server:

export HEVY_API_KEY=your-hevy-api-key docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

For an MCP client, store the key in a protected environment file and configure the client to launch Docker:

{ "mcpServers": { "hevy": { "command": "docker", "args": [ "run", "-i", "--rm", "--env-file", "/absolute/path/to/hevy-mcp.env", "ghcr.io/chrisdoc/hevy-mcp:latest" ] } } }

Pin an exact image tag such asghcr.io/chrisdoc/hevy-mcp:X.Y.Zwhen you need reproducible upgrades.

You can also add the npm server to supported clients withadd-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

Try one of these after restarting or reconnecting your MCP client:

- “Give me a training summary for the last four weeks.”
- “What routines do I have saved on Hevy?”
- “Show my three most recent workouts.”
- “Find exercise templates containing squat.”
- “Which Hevy account is connected?”

Your assistant should ask for approval before mutation tools when the client supports tool confirmations.

Hosted: Your AI assistant → Streamable HTTP → Cloudflare Worker → Hevy API Local: Your AI assistant → MCP over stdio → local hevy-mcp → Hevy API

The hosted endpoint creates a fresh MCP server and Hevy client for each request. It validates the supplied key with Hevy, keeps no shared user session, and does not persist the key. The local server follows the same tool contract but runs on your machine and receives the key through its child-process environment.

In either mode, read tools retrieve data; mutation tools create or replace data only when your assistant calls them.

These server-provided MCP prompts coordinate common multi-step workflows:

[!NOTE] With MCP SDK v1.29.0, clients invokinganalyze-workout-progresswith its default value must sendarguments: {}. Omitting the entireargumentsobject is rejected by that SDK version before the default is applied.

hevy-mcpregisters 22 tools. Read-only tools are safe for exploration; create and update tools are exposed with MCP mutation annotations so compatible clients can request confirmation.

create-routinerequires a top-levelroutineenvelope with a requiredexercisesarray; fields use snake_case at every level:

{ "routine": { "title": "Full Body A", "folder_id": 123, "notes": "First four exercises are the minimum viable workout", "exercises": [ { "exercise_template_id": "30E293E3", "superset_id": null, "rest_seconds": 120, "notes": "Controlled active ROM", "sets": [ { "type": "normal", "rep_range": { "start": 6, "end": 10 } } ] } ] } }

The Hevy API currently exposes no delete endpoints for workouts, routines, routine folders, exercise templates, or body measurements, so there are no corresponding delete tools.

It is the quickest way to usehevy-mcp: there is nothing to install or keep running locally, and it exposes the same 22 tools as the npm package and Docker image.

The Cloudflare Worker uses statelessStreamable HTTPatPOST /mcp. Clients must send their Hevy API key as a fixed authorization header:

{ "mcpServers": { "hevy": { "url": "https://mcp.hevy-mcp.dev/mcp", "headers": { "Authorization": "Bearer your-hevy-api-key" } } } }

The bearer value is your Hevy API key, not an OAuth token. The Worker validates the key with Hevy on each request, does not store it, and forwards it upstream only as Hevy's requiredapi-keyheader.

OAuth for Claude.ai and other remote MCP clients

The hosted production Worker is deployed with anOAUTH_KVnamespace binding, so it exposes a full OAuth 2.1 layer for clients that cannot send a fixed header, such as Claude.ai custom connectors. Self-hosted Workers can opt in by following theOAUTH_KVsetup inCONTRIBUTING.md:

- RFC 8414 / RFC 9728 discovery metadata under/.well-known/
- Client ID Metadata Documents (CIMD), with dynamic client registration (/register) as a fallback, and PKCE token exchange (/token)
- An/authorizepage where you paste your Hevy API key once; the key is validated with Hevy and stored encrypted inside the OAuth grant

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get-workouts

get-workout

get-workout-count

get-workout-events

create-workout

update-workout

get-routines

get-routine

create-routine

update-routine

get-exercise-templates

get-exercise-template

get-routine-folders

get-routine-folder

create-routine-folder

Claude Desktop / Cursor

McpServers

OAuth for Claude.ai and other remote MCP clients

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`get-workouts`

`get-workout`

`get-workout-count`

`get-workout-events`

`create-workout`

`update-workout`

`get-routines`

`get-routine`

`create-routine`

`update-routine`

`get-exercise-templates`

`get-exercise-template`

`get-routine-folders`

`get-routine-folder`

`create-routine-folder`