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").

Related MCP server: Hevy MCP

Tools

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.