hevy-mcp: Hevy workouts for your AI assistant

hevy-mcp connects MCP-compatible assistants such as Claude Desktop and Cursor to the Hevy fitness API. Ask about workout history, analyze progress, browse routines and exercises, or create and update Hevy data without leaving your assistant.

A Hevy API key, available with Hevy PRO, is required.

Quick Start

Use local stdio when your MCP client can launch a command. Hosted Streamable HTTP setup is documented below but is temporarily unavailable.

Option A: Local stdio

The npm package and official container are stdio-only MCP executables. Your client starts the process and communicates through standard input/output; this is not an interactive terminal command or an HTTP service.

npx

Requires Node.js 20 or newer, as declared by the package metadata.

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json) both accept an mcpServers entry like this:

• Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop on Windows: %APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"hevy": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

bunx

Requires Bun. Use the same client configuration with a Bun launcher:

{
	"mcpServers": {
		"hevy": {
			"command": "bunx",
			"args": ["hevy-mcp@latest"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

Docker

Official images support linux/amd64 and linux/arm64. Keep stdin open with -i because the container runs the same stdio server:

export HEVY_API_KEY=your-hevy-api-key
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

For an MCP client, store the key in a protected environment file and configure the client to launch Docker:

{
	"mcpServers": {
		"hevy": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"--env-file",
				"/absolute/path/to/hevy-mcp.env",
				"ghcr.io/chrisdoc/hevy-mcp:latest"
			]
		}
	}
}

Pin an exact image tag such as ghcr.io/chrisdoc/hevy-mcp:X.Y.Z when you need reproducible upgrades.

You can also add the local npm server to supported clients with add-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

Option B: Hosted Streamable HTTP — temporarily unavailable

[!WARNING] https://hevy.chrisdoc.dev/mcp is currently intercepted by an interactive Cloudflare challenge, so non-browser MCP clients cannot connect. Use local stdio until the route is restored.

When available, the hosted endpoint does not require Node.js, Bun, or Docker:

https://hevy.chrisdoc.dev/mcp

Configure a remote MCP server in your client and send your Hevy API key as a fixed authorization header. Exact configuration keys vary by client; clients that use url and headers commonly accept this shape:

{
	"mcpServers": {
		"hevy": {
			"url": "https://hevy.chrisdoc.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

The hosted transport is stateless Streamable HTTP at POST /mcp. The bearer value is a custom Hevy API credential, not OAuth. The endpoint does not expose a legacy SSE or GET event stream, and GET and DELETE requests return 405. Clients that require OAuth discovery, dynamic registration, token refresh, or a legacy SSE transport are not compatible unless they can send the fixed custom header above.

How to verify it is working

Restart or reconnect your MCP client after saving the configuration, then try:

• "What routines do I have saved on Hevy?"
• "Show my most recent workouts."
• "Which Hevy account is connected?"
• "Find exercise templates containing squat."

The assistant should ask for approval before mutation tools when the client supports tool confirmations.

Guided MCP prompts

These server-provided prompts coordinate multiple tools for common workflows:

[!IMPORTANT] With MCP SDK v1.29.0, invoking analyze-workout-progress with its default weeks value requires clients to send arguments: {}. Omitting the entire arguments object is rejected by that SDK version before the default is applied.

Capabilities

hevy-mcp registers 23 tools:

The Hevy API currently exposes no delete endpoints for workouts, routines, routine folders, exercise templates, or body measurements, so there are no corresponding delete tools.

Resources