Skip to main content

​
Overview

Hevy HTTP MCP is configured entirely through environment variables. All credentials and server settings are loaded from a .env file or your system environment, ensuring no secrets are committed to your codebase.

​
Environment Setup

Create a .env file in your project root: 
cp .env.example .env
Then edit .env with your actual values.

​
Required Variables

​
HEVY_API_KEY
string
required
Your Hevy API key for authenticating with the Hevy API.How to get it: Visit hevy.com/settings?developer (requires Hevy Pro subscription)
HEVY_API_KEY=your_hevy_api_key_here
​
MCP_API_KEY
string
required
A secret key that MCP clients must send to access this server. Choose any secure random string.
This key protects your MCP server from unauthorized access. Use a strong, randomly generated value.
MCP_API_KEY=your_mcp_access_key_here

​
Optional Variables

​
PORT
number
default:"3000"
HTTP port the server listens on.
PORT=3000
​
HOST
string
default:"127.0.0.1"
Hostname to bind to. Use 0.0.0.0 to listen on all network interfaces.
HOST=127.0.0.1
For local development, use 127.0.0.1. For remote access or Docker deployments, use 0.0.0.0.
​
LOG_LEVEL
string
default:"info"
Logging verbosity level.Options: debug | info | warn | error
LOG_LEVEL=info

​
Complete Example

Here’s a complete .env file with all variables: 
# Required
HEVY_API_KEY=your_hevy_api_key_here
MCP_API_KEY=your_mcp_access_key_here

# Optional (these are the defaults)
PORT=3000
HOST=127.0.0.1
LOG_LEVEL=info

​
Configuration Loading

The server validates all required environment variables at startup. If any required variable is missing, the server will exit with an error message: 
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    console.error(`[config] Missing required environment variable: ${name}`);
    process.exit(1);
  }
  return value;
}

​
Security Best Practices

Never commit your .env file to version control. The .env file is gitignored by default.
  • Generate strong keys: Use a password manager or openssl rand -hex 32 to generate secure API keys
  • Rotate regularly: Change your MCP_API_KEY periodically, especially if you suspect it’s been compromised
  • Restrict access: Keep your HEVY_API_KEY private—it provides full access to your Hevy workout data
  • Use environment-specific configs: Use different .env files for development, staging, and production

​
Verifying Configuration

After configuring your environment variables, start the server: 
bun run start
You should see output confirming the configuration: 
[info] Starting hevy-http-mcp server…
[info] All Hevy MCP tools registered
[info] hevy-http-mcp listening on http://127.0.0.1:3000/mcp
If any required variables are missing, you’ll see an error immediately: 
[config] Missing required environment variable: HEVY_API_KEY

Build docs developers (and LLMs) love

Get started for freeTalk to us