Skip to main content

​
Installation

Get Hevy HTTP MCP running on your machine with these step-by-step instructions.

​
Prerequisites

Before installing, ensure you have the following:
1

Install Bun

Hevy HTTP MCP requires Bun v1.0 or higher.
curl -fsSL https://bun.sh/install | bash
Verify your installation:
bun --version
2

Get a Hevy Pro account

You need a Hevy Pro subscription to access the Hevy API.
The Hevy API is only available to Hevy Pro subscribers. Free accounts cannot generate API keys.
If you don’t have Hevy Pro yet, upgrade at hevyapp.com.
3

Generate your Hevy API key

  1. Log in to Hevy on the web
  2. Navigate to Settings → Developer
  3. Generate a new API key
  4. Save the key securely - you’ll need it for configuration
Keep your API key secure. It grants full access to your workout data.

​
Install from source

1

Clone the repository

git clone <repo-url> hevy-http-mcp
cd hevy-http-mcp
2

Install dependencies

Use Bun to install all required packages:
bun install
This installs:
  • elysia - Web framework
  • elysia-mcp - MCP protocol implementation
  • ofetch - HTTP client for Hevy API
3

Configure environment variables

Copy the example environment file and edit it with your credentials:
cp .env.example .env
Open .env in your editor and configure the required variables:
# Required: Your Hevy API key from https://hevy.com/settings?developer
HEVY_API_KEY=your_hevy_api_key_here

# Required: A secure random string for MCP client authentication
MCP_API_KEY=your_mcp_access_key_here

# Optional: Server configuration
# PORT=3000
# HOST=127.0.0.1
# LOG_LEVEL=info
Never commit your .env file to version control. It contains sensitive credentials.

​
Environment variables explained

VariableRequiredDefaultDescription
HEVY_API_KEYYes-Your Hevy API key from the developer settings
MCP_API_KEYYes-Secret key that MCP clients must use to authenticate
PORTNo3000HTTP port for the MCP server
HOSTNo127.0.0.1Hostname to bind the server to
LOG_LEVELNoinfoLogging verbosity: debug, info, warn, or error
Generate a secure random string for MCP_API_KEY using:
openssl rand -base64 32
4

Start the server

Run the MCP server:
bun run start
You should see output confirming the server is running:
Starting hevy-http-mcp server…
All Hevy MCP tools registered
hevy-http-mcp listening on http://127.0.0.1:3000/mcp

​
Development mode

For development with hot-reload: 
bun run dev
The server will automatically restart when you modify source files.

​
Verify installation

Test that your server is running and authenticated correctly: 
curl -H "Authorization: Bearer your_mcp_access_key_here" \
  http://localhost:3000/mcp
You should receive a valid MCP protocol response.
Replace your_mcp_access_key_here with the actual MCP_API_KEY from your .env file.

​
Next steps

Quickstart

Connect your first MCP client and make API calls

Configuration

Learn about advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us