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

Advanced configuration

The local executable does not support PORT, HEVY_MCP_TRANSPORT, or --transport. It always uses stdio and does not provide local HTTP or SSE behavior. Use the hosted endpoint after its route is restored, or deploy the separate Cloudflare Worker when Streamable HTTP is required now.

Cache behavior

search-exercise-templates and hevy://exercise-templates share a server-scoped in-memory catalog cache:

• Entries live for five minutes and the cache holds at most one catalog.
• Concurrent catalog requests share an in-flight fetch when possible.
• search-exercise-templates accepts refresh: true to invalidate the cache.
• Paginated get-exercise-templates calls always fetch their requested page.
• Each hosted Worker request gets a fresh cache, preventing cross-key sharing.

Security and mutations

• Keep HEVY_API_KEY out of source control, URLs, logs, and screenshots.
• Local clients provide the key through the child process environment. Hosted clients send it only in Authorization: Bearer .
• The hosted Worker validates each key with Hevy, does not store it, and sends it upstream only as Hevy’s api-key header.
• Browser requests to a self-hosted Worker must exactly match an origin in MCP_ALLOWED_ORIGINS; wildcard CORS is intentionally unsupported.
• Create operations can produce duplicates when retried. Update operations replace existing records. Review tool inputs and use client confirmations.

Contributing and self-hosting

Developer setup, testing lanes, generated-client workflows, Cloudflare Worker deployment, and pull request rules live in the contributor guide.

License and acknowledgements

• License: MIT
• Credits: Model Context Protocol and Hevy Fitness