Minimal Hevy MCP

A small local Model Context Protocol server that lets an agent read Hevy workout data and create workout routines through Hevy's public API.

Included tools

• hevy_list_workouts
• hevy_get_workout
• hevy_list_routines
• hevy_get_routine
• hevy_search_exercises
• hevy_get_exercise_history
• hevy_create_workout
• hevy_create_routine

The first six tools are read-only. hevy_create_workout and hevy_create_routine write to the connected Hevy account and are annotated as non-idempotent mutations.

hevy_create_routine creates a reusable plan for a future session. hevy_create_workout logs an already-completed session using actual start/end times and set results. It defaults completed workouts to private and rejects sets without a recorded performance metric.

Requirements

• Node.js 20 or newer
• A Hevy Pro account and API key from https://hevy.com/settings?developer

Install and validate

npm install
npm run check
npm run build
npm run smoke

Run locally

export HEVY_API_KEY="your-key"
npm start

The server communicates over stdin/stdout, so it will appear to wait silently when run directly. An MCP host is expected to start it and communicate with it.

Add it to Codex

Build the server first, make HEVY_API_KEY available to the environment that starts Codex, then run:

codex mcp add hevy -- node /absolute/path/to/hevy-mcp/dist/index.js

Restart Codex after adding the server. Verify the configuration with:

codex mcp list

Do not commit the API key or pass it as a tool argument. The MCP reads it only from HEVY_API_KEY and sends it to Hevy in the required api-key header.

Suggested first request

Read my five most recent workouts and summarize frequency, exercise selection, and obvious progression patterns. Do not create or update anything.

When asking the agent to create a routine, require it to show the full routine and get your approval before calling hevy_create_routine.

When logging a completed workout, give the agent the actual exercises, set results, and times. Require it to show the complete workout and get your approval before calling hevy_create_workout. The agent must never invent completed results.