hevy

This MCP server connects to the official Hevy API and exposes workout, routine, and exercise data to AI assistants via multiple transport modes. It supports stdio mode for Claude Desktop integration, as well as SSE for remote access (for example through Poke.com). The server implements a suite of MCP tools, including workout management (get-workouts, get-workout, create-workout, update-workout, get-workout-count, get-workout-events), routine management (get-routines, get-routine, create-routine, update-routine, delete-routine), exercise data access (get-exercise-templates, get-exercise-template, get-exercise-progress, get-exercise-stats), and folder operations for routines (get-routine-folders, get-routine-folder, create-routine-folder, update-routine-folder, delete-routine-folder). To use it, configure the environment with your Hevy API credentials and choose the transport mode. In SSE mode, protect remote access with an AUTH_TOKEN and pass it in the Authorization header when connecting.

Prerequisites:

• Node.js v18 or newer
• Git
• npm (comes with Node.js)

1. Clone the repository

git clone https://github.com/meimakes/hevy-mcp-server
cd hevy-mcp-server

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env

Edit the .env file and add your Hevy API credentials and transport settings, for example:

HEVY_API_KEY=your_hevy_api_key_here
HEVY_API_BASE_URL=https://api.hevyapp.com
TRANSPORT=stdio                    # stdio | sse | both
PORT=3004                          # Port for SSE/HTTP mode
HOST=127.0.0.1                     # Host for SSE/HTTP mode
SSE_PATH=/mcp                      # SSE endpoint path
HEARTBEAT_INTERVAL=30000           # ms - keep connection alive
AUTH_TOKEN=your_generated_token_here # Required for remote SSE access

4. Build the project (optional but recommended for production)

npm run build

5. Run the server

• For Claude Desktop (stdio mode):

npm run dev

• For SSE mode (remote access):

npm start

Note: If you’re using the SSE mode with public access (e.g., via ngrok or Poke.com), ensure AUTH_TOKEN is set and supplied in the Authorization header: "Authorization: Bearer <AUTH_TOKEN>".

Security is important when exposing data over SSE. Always enable AUTH_TOKEN for remote access and never commit your .env file. If you’re running SSE behind a reverse proxy or tunnel, ensure the token is transmitted securely. The TRANSPORT setting allows you to run in stdio mode for local Claude Desktop usage, SSE mode for remote clients, or both. When using auto-generated tokens, you can create one with npm run generate-token or via OpenSSL (openssl rand -hex 32). Remember to keep your Hevy API key and BASE URL secure and never share them publicly.