Hevy MCP

🚀 Hevy MCP Server

The MCP server for the Hevy fitness API, featuring HTTP transport and session management. Written entirely in Rust for low memory management and offering proper async support!

🚀 Quick Start

Quick start with Docker

docker pull ghcr.io/zelosleone/hevy-mcp-server:latest
docker run -e HEVY_API_KEY=your-api-key -p 5000:5000 ghcr.io/zelosleone/hevy-mcp-server:latest

✨ Features

This server is an MCP server designed for the Hevy fitness API, with HTTP transport and session management. It's written in Rust for low memory management and has proper async support.

📦 Installation

Requirements

• Hevy PRO subscription
• Hevy API key from https://hevy.com/settings?developer

Configuration

Operating modes

Single - user mode

Set the HEVY_API_KEY environment variable. All sessions share this key -- no query parameter needed.

HEVY_API_KEY=your-api-key ./target/release/hevy-mcp-server

Multi - user mode

Leave HEVY_API_KEY unset. Each client must pass its own key as a query parameter during initialization:

POST /?apikey=xxx

If neither method provides a key, the server responds with an error.

💻 Usage Examples

HTTP transport

The server exposes two endpoints on the configured path (default /):

POST {path} -- MCP requests

Send JSON - RPC requests and notifications. The first request must be an initialize call. The response includes an Mcp - Session - Id header that must be sent on all subsequent requests.

POST /
Content-Type: application/json
Mcp-Session-Id: <session-id>

Session lifecycle

• A new session is created on each initialize request and a UUID is returned via the Mcp - Session - Id response header.
• All non - initialize requests must include the Mcp - Session - Id header; requests without it are rejected.
• Sessions are automatically cleaned up after HEVY_SESSION_TIMEOUT_SECS seconds of inactivity (default 3600). A background task checks for expired sessions every 60 seconds.
• Sessions can also be deleted explicitly via the DELETE endpoint.

Available tools

Workouts

• get_workouts -- List workouts with pagination. Params: page (1 - indexed), page_size (max 10).
• get_workouts_count -- Get the total number of workouts on the account.
• get_workout_events -- List workout update/delete events since a timestamp. Params: page, page_size (max 10), since (ISO 8601).
• get_workout -- Get a single workout by ID. Returns full details including exercises and sets.
• create_workout -- Create a workout. Required: title, start_time, end_time (ISO 8601), exercises with sets. Optional: is_private, description.
• update_workout -- Replace an existing workout by ID. Same fields as create_workout plus id.

Routines

• get_routines -- List routines with pagination. Params: page, page_size (max 10).
• get_routine -- Get a single routine by ID, including exercises and set templates.
• create_routine -- Create a routine (workout template). Required: title, folder_id, exercises with sets. Optional: notes.
• update_routine -- Replace an existing routine by ID. Same fields as create_routine plus id.

Exercise Templates

• get_exercise_templates -- List exercise templates from the Hevy library. Params: page, page_size (max 100).
• get_exercise_template -- Get an exercise template by ID, including muscle groups and equipment.
• create_exercise_template -- Create a custom exercise template. Required: title, exercise_type, equipment_category, muscle_group. Optional: other_muscles.

Routine Folders

• get_routine_folders -- List routine folders with pagination. Params: page, page_size (max 10).
• get_routine_folder -- Get a routine folder by ID.
• create_routine_folder -- Create a folder to organize routines. Required: title.

Exercise History

• get_exercise_history -- Get workout history for an exercise template. Required: exercise_template_id. Optional: start_date, end_date (ISO 8601).

From source

cargo build --release
HEVY_API_KEY=your-api-key ./target/release/hevy-mcp-server

The server binds to 127.0.0.1:3000 by default. Override with HEVY_HTTP_ADDR:

HEVY_API_KEY=your-api-key HEVY_HTTP_ADDR=0.0.0.0:8080 ./target/release/hevy-mcp-server

📄 License

MIT License - See LICENSE for details.

📚 Documentation

• https://api.hevyapp.com/docs/