Skip to main content

​
Quickstart

Get up and running with Hevy HTTP MCP in minutes. This guide walks you through starting the server and making your first request.
Make sure you’ve completed the installation steps before proceeding.

​
Start the server

1

Navigate to your project directory

cd hevy-http-mcp
2

Verify your environment configuration

Ensure your .env file has both required keys set:
cat .env
You should see:
HEVY_API_KEY=your_hevy_api_key_here
MCP_API_KEY=your_mcp_access_key_here
If these values are still set to the placeholder text, update them with your actual API keys before continuing.
3

Start the MCP server

bun run start
The server will start and display:
Starting hevy-http-mcp server…
All Hevy MCP tools registered
hevy-http-mcp listening on http://127.0.0.1:3000/mcp
Your MCP server is now running and ready to accept requests.

​
Use the MCP inspector

The MCP Inspector is a web UI that lets you explore and test all available tools interactively.
1

Open a new terminal

Keep your server running in the first terminal, and open a new terminal window or tab.
2

Launch the inspector

bun run inspect
This opens the MCP Inspector UI in your browser, pointed at http://localhost:3000/mcp.
3

Explore available tools

In the inspector, you’ll see all registered tools organized by category:
  • Workouts - get-workouts, get-workout, create-workout, update-workout, get-workout-count, get-workout-events
  • Routines - get-routines, get-routine-by-id, create-routine, update-routine
  • Exercise Templates - get-exercise-templates, get-exercise-template
  • Routine Folders - get-routine-folders, create-routine-folder, get-routine-folder
Click any tool to see its parameters and try it out.

​
Connect an MCP client

Connect Hevy HTTP MCP to an MCP-compatible client like Claude Desktop or Cursor.

​
Claude Desktop / Cursor

Add the following configuration to your MCP settings: 
{
  "mcpServers": {
    "hevy": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your_mcp_access_key_here"
      }
    }
  }
}
Replace your_mcp_access_key_here with your actual MCP_API_KEY from the .env file.

​
Authentication

All requests to the MCP server must include the Authorization header with your MCP_API_KEY: 
Authorization: Bearer <MCP_API_KEY>
Requests without a valid key receive 401 (missing key) or 403 (invalid key) responses.

​
Example: Query your workouts

Once connected, you can query your workout data through the MCP client.

​
Using the inspector

  1. Select the get-workouts tool
  2. Set parameters (optional):
    • page: 0
    • pageSize: 10
  3. Click “Execute”
  4. View your workout history in the response

​
Using an AI client

In Claude Desktop or another MCP-compatible AI client, you can ask natural language questions: 
Show me my last 5 workouts

What exercises did I do yesterday?

Create a new push day routine with bench press, overhead press, and tricep dips
The AI will automatically call the appropriate Hevy MCP tools to fulfill your request.

​
Example: Get workout count

Test the connection with a simple API call using curl: 
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your_mcp_access_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get-workout-count",
      "arguments": {}
    },
    "id": 1
  }'
This follows the MCP protocol specification for tool invocation over HTTP.

​
Common issues

​
401 Unauthorized

You’re missing the Authorization header. Ensure your MCP client configuration includes: 
"headers": {
  "Authorization": "Bearer your_mcp_access_key_here"
}

​
403 Forbidden

The MCP_API_KEY in your request doesn’t match the one in your server’s .env file. Verify both values are identical.

​
Connection refused

The server isn’t running. Start it with: 
bun run start

​
Hevy API errors

If you receive errors from the Hevy API:
  1. Verify your HEVY_API_KEY is correct
  2. Ensure your Hevy Pro subscription is active
  3. Check the API key hasn’t been revoked at Hevy settings

​
Next steps

Available tools

Explore all available Hevy API tools and their parameters

Configuration

Learn about advanced configuration options

Client setup

Detailed setup guides for different MCP clients

Architecture

Learn about the architecture and design patterns

​
Development workflow

For active development: 
# Terminal 1: Run server with hot-reload
bun run dev

# Terminal 2: Watch logs and test changes
bun run inspect
The server automatically reloads when you modify source files in src/.

Build docs developers (and LLMs) love

Get started for freeTalk to us