hevy-mcp-server

A complete, open-source single tenant MCP server for Hevy's public API. Every endpoint Hevy exposes is reachable through one of the tools below -- workouts, routines, routine folders, exercise templates (including custom exercises), per-exercise history, and body measurements.

Runs two ways:

• Locally over stdio -- for Claude Desktop / Claude Code, zero hosting required.

• Remotely over HTTP -- for claude.ai / Cowork connectors, deployable to Fly.io with the included Dockerfile.

View the full product and technical design here.

Tools

12 tools cover all 21 endpoint paths in Hevy's public API (several are consolidated behind one tool via a view/action parameter to avoid near-duplicate tools). Full list with exact endpoint coverage: docs/tools.md.

Quick start (local, stdio)

Requires Node.js 20+ and a Hevy Pro subscription. Grab your Hevy API key first.

npx hevy-mcp-server

Point your MCP client (Claude Desktop, Claude Code, etc.) at it. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["hevy-mcp-server"],
      "env": {
        "HEVY_API_KEY": "your-api-key-here",
        "HEVY_READ_ONLY": "false"
      }
    }
  }
}

Configuration

HTTP mode (below) needs three more: PORT, PUBLIC_URL, MCP_HTTP_PASSWORD. See .env.example for all of them with descriptions.

Remote (HTTP) deployment on Fly.io

The HTTP transport is gated by OAuth (required for claude.ai/Cowork connector approval). This is single-tenant OAuth: there's no concept of separate user accounts, it just gates access to your instance behind one shared password. See docs/architecture.md for why and how.

1. Install flyctl and fly auth login.

2. fly launch --no-deploy from this directory (it will read fly.toml; rename the app there first if you want a specific subdomain).

3. Set secrets (never put these in fly.toml, which is committed to git):

   fly secrets set HEVY_API_KEY=your-api-key-here
   fly secrets set MCP_HTTP_PASSWORD=choose-a-strong-password

4. Edit fly.toml's PUBLIC_URL to match your actual *.fly.dev hostname (or custom domain), then:

   fly deploy

5. In claude.ai / Cowork, add a custom connector pointing at https://<your-app>.fly.dev/mcp. You'll be redirected to a login page on your own instance -- enter MCP_HTTP_PASSWORD to approve the connection.

Notes:

• Single shared-cpu-1x machine, no volume. OAuth session state (registered clients, tokens) lives in memory and is lost on redeploy or restart -- you'll just need to reconnect the connector afterwards. Acceptable trade-off for a low-traffic personal instance; see the TDD.

• fly.toml's [http_service] is configured to stay always-on (not scaled to zero) for exactly that reason -- a stop/start cycle would otherwise force reconnection too.

• Hevy's docs ask that scheduled/automated syncs avoid firing exactly on the hour -- stagger any cron-style usage by a random minute.

Development

npm install
npm run dev:stdio      # run src/stdio.ts directly with tsx
npm run dev:http       # run src/http.ts directly with tsx
npm run typecheck
npm run lint            # biome check
npm run lint:fix
npm test
npm run build           # bundles dist/stdio.js and dist/http.js with tsup

See docs/architecture.md for the repo layout and request-flow details.

Skills

skills/ bundles ready-made agent workflows on top of these tools (workout logging, routine building, progress reviews, etc.) -- see that folder's README for the full index.

License

MIT -- see LICENSE.