@diecoscai/hevy-mcp

Model Context Protocol server for the Hevy fitness API. Manage workouts, routines, exercises, and body measurements from any MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code, and anything else that speaks MCP over stdio.

Overview

This MCP server exposes the public Hevy API (api.hevyapp.com/v1) as 22 strongly-typed tools. LLM agents can list workouts, create routines, look up exercise templates, track body measurements, and follow a delta-sync feed — all without bespoke glue code on the client.

Design goals:

• Safe by default. Write operations return a { dry_run: true, would_send: { ... } } preview unless HEVY_MCP_ALLOW_WRITES=1 is set. The Hevy API has no DELETE on any resource, so accidental writes are permanent; dry-run is the brake.
• Validated at the edge. Every tool input is checked with Zod before a single byte crosses the network. Oversized titles, unknown fields, out-of-range page sizes, and invalid enums fail fast with SEP-1303-shaped errors the model can self-correct.
• Zero extra setup. Authentication is a single environment variable — HEVY_API_KEY. No wizards, no config files; just paste the snippet for your client.

Schemas are generated from Hevy's own OpenAPI spec and re-synced automatically, so the server adapts to upstream changes instead of drifting. Writes are dry-run by default; every public endpoint is covered.

Project status

Maintenance mode. Feature-complete for Hevy's public API. Schemas are generated from Hevy's OpenAPI spec; a scheduled workflow re-syncs them weekly and opens a PR on any change, and a live integration run catches undocumented server changes. Bug reports and PRs welcome via the issue tracker.

Prerequisites

• Node.js 20 or later (node --version).
• A Hevy Pro subscription — the public API is a Pro feature.
• A Hevy API key from https://hevy.com/settings?developer.

Quick setup

The fastest path is the setup subcommand — it validates your key and writes a config file the server picks up automatically:

npx @diecoscai/hevy-mcp setup

It prompts for your Hevy Pro API key (from https://hevy.com/settings?developer), checks it against the live API, asks whether to enable write operations, and saves everything to ~/.config/hevy-mcp/config.json (mode 0600). Then add the server to your MCP client with no env block needed:

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"]
    }
  }
}

Restart the client — the 22 Hevy tools appear in the tools panel.

Prefer environment variables? Skip setup and pass HEVY_API_KEY (and optionally HEVY_MCP_ALLOW_WRITES=1) in the env block instead — see Configuration. Env vars always take precedence over the config file.

Note on bare invocation. Running npx @diecoscai/hevy-mcp with no arguments starts a stdio MCP server and blocks, waiting for an MCP client to connect over its stdin/stdout. You don't run it in a terminal yourself — your MCP client spawns it. Use npx @diecoscai/hevy-mcp --help, --version, or setup for a non-blocking invocation.

Write tools are dry-run by default. The first time you ask the server to create or update anything (a workout, a routine, a body measurement) you'll see a preview payload, not a real change. Enable writes by answering "yes" during setup, or by setting HEVY_MCP_ALLOW_WRITES=1 in the env block — see Safety.

Run from source

You can also run the server directly from a local clone instead of via npx. Useful if you want to pin a specific commit, debug a tool locally, or run an unreleased version. Contributors should use Development below instead.

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build

Then point your MCP client at the built entry instead of npx @diecoscai/hevy-mcp:

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp/dist/index.js"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

The env block (including HEVY_MCP_ALLOW_WRITES) works identically to the npx snippets below.

Configuration

Each MCP client spawns the server as a stdio subprocess with HEVY_API_KEY in its env block.

Claude Desktop

Config path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json (Anthropic does not ship an official Linux build of Claude Desktop as of 2026; the path applies only to unofficial community builds.)

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

Add "HEVY_MCP_ALLOW_WRITES": "1" to the env block to enable write tools.

Claude Code CLI

claude mcp add hevy --env HEVY_API_KEY=PASTE_YOUR_KEY_HERE -- npx -y @diecoscai/hevy-mcp

To enable writes, append --env HEVY_MCP_ALLOW_WRITES=1.

Cursor

Config path: ~/.cursor/mcp.json. Same shape as Claude Desktop:

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

VS Code (native MCP support, 1.102+)

Create .vscode/mcp.json at the root of your workspace (or put the same shape under a user-level MCP config if your VS Code build supports one):

{
  "servers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

If you use a third-party MCP extension that expects a different shape, check its docs — VS Code's native MCP integration landed in 1.102.

See docs/configuration.md for troubleshooting and client-specific notes, and docs/examples.md for end-to-end flows you can run with a connected MCP client.

Safety — dry-run writes

Every POST and PUT tool handler checks HEVY_MCP_ALLOW_WRITES at call time:

• Unset (default) — the tool returns a preview instead of making the HTTP call:

  config.json

  Copy

  {
    "dry_run": true,
    "would_send": {
      "method": "POST",
      "path": "/v1/routine_folders",
      "body": { "routine_folder": { "title": "Push days" } }
    },
    "hint": "set HEVY_MCP_ALLOW_WRITES=1 to execute"
  }
  

• Set to 1 — the tool performs the real request.

The Hevy API has no DELETE endpoint on any resource. A bad write cannot be rolled back from the client — it will persist on your account until you manually fix it in the Hevy app. Dry-run is the first line of defence; explicit opt-in for writes is the second.

Tool reference (summary)

The server exposes 23 tools grouped by resource. See docs/tools.md for input schemas and examples.

User

Workouts

Routines

Routine folders

Exercise templates

Body measurements