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.