hevy-mcp

MCP (Model Context Protocol) server for the Hevy workout tracker API.

Lets Claude (or any MCP client) read and write your Hevy data: workouts, routines, exercise templates, routine folders, exercise history, and body measurements.

Requirements: Node.js >= 18, a Hevy Pro account, and an API key from https://hevy.com/settings?developer.

Usage

.mcp.json (project-level, Claude Code)

A .mcp.json file in a project's root directory makes MCP servers available to everyone who runs Claude Code inside that project — check it into git and the whole team gets the server automatically.

Step by step:

1. Create a file named .mcp.json in the root of your project (same folder as .git), or run:

   claude mcp add hevy --scope project -- npx -y @antnsn/hevy-mcp
   

   which creates/updates it for you.

2. Make sure it contains:

   {
     "mcpServers": {
       "hevy": {
         "command": "npx",
         "args": ["-y", "@antnsn/hevy-mcp"],
         "env": {
           "HEVY_API_KEY": "${HEVY_API_KEY}"
         }
       }
     }
   }
   

3. Provide the key. ${HEVY_API_KEY} is expanded from your environment at launch, so the key never lives in the file (safe to commit). Export it in your shell profile or session:

   export HEVY_API_KEY=your-api-key
   

4. Start (or restart) claude inside the project. First use prompts you to approve the project's MCP servers; approve and the hevy tools are available. Verify with /mcp.

Claude Code (global)

claude mcp add hevy -s user --env HEVY_API_KEY=your-api-key -- npx -y @antnsn/hevy-mcp

Claude Desktop

Add to claude_desktop_config.json:

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

Global install (alternative to npx)

If npx is slow or blocked in your environment — common on corporate machines with npm security policies (e.g. allow-scripts guards) — install once globally:

npm install -g @antnsn/hevy-mcp

Then use hevy-mcp as the command in any of the configs above:

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "${HEVY_API_KEY}"
      }
    }
  }
}

Note: ${HEVY_API_KEY} interpolation only works in Claude Code's .mcp.json. Claude Desktop does not expand environment variables — put the literal key there ("HEVY_API_KEY": "your-api-key").

Tools

Tool	Description
get-workouts	Paginated list of workouts
get-workout	Single workout by ID
get-workout-count	Total workout count
get-workout-events	Workout update/delete events since a date (sync)
create-workout	Log a completed workout
update-workout	Update a workout (full overwrite)
get-routines	Paginated list of routines
get-routine	Single routine by ID
create-routine	Create a routine
update-routine	Update a routine (full overwrite)
get-exercise-templates	Paginated exercise templates
get-exercise-template	Single exercise template by ID
create-exercise-template	Create a custom exercise
get-routine-folders	Paginated routine folders
get-routine-folder	Single folder by ID
create-routine-folder	Create a routine folder
get-exercise-history	History for an exercise template (progress tracking)
get-body-measurements	Paginated body measurements
get-body-measurement	Body measurement by date
create-body-measurement	Create a body measurement entry
update-body-measurement	Update a body measurement (full overwrite)
get-user-info	Authenticated user info

Notes

• The Hevy API is v0 ("use at your own risk" per Hevy's docs) — endpoints may change.
• The API has no delete endpoints; anything created can only be deleted manually in the Hevy app.
• update-workout, update-routine, and update-body-measurement overwrite the full record; fetch first, modify, then update.

Contributing

From source

git clone https://github.com/antnsn/hevy-mcp.git
cd hevy-mcp
npm install
npm run build

When running from a clone, the key can also live in a .env file in the project root (gitignored) instead of the environment:

echo 'HEVY_API_KEY=your-api-key' > .env
chmod 600 .env

The repo's .mcp.json then picks the server up automatically when running claude inside the repo. Note: the .env file only works for clones — the npm-installed package looks for it next to its own install location, so use the env config shown above instead.

Development

npm run dev        # run from source via tsx
npm run typecheck  # type-check without emitting

Test interactively with the MCP Inspector (pass the key explicitly — the Inspector does not inherit your shell environment):

npx @modelcontextprotocol/inspector -e HEVY_API_KEY=$HEVY_API_KEY node dist/index.js

The upstream OpenAPI spec is vendored at docs-openapi.json, extracted from the Swagger UI at https://api.hevyapp.com/docs/ (the spec is embedded in swagger-ui-init.js; there is no standalone spec URL).

Issues and PRs welcome at https://github.com/antnsn/hevy-mcp.