Skip to main content
Official Hevy MCP Docker images are published at ghcr.io/chrisdoc/hevy-mcp with support for both linux/amd64 and linux/arm64. The container runs the stdio MCP server — the same implementation as the npm package — so any MCP client that can launch a local command can use it without installing Node.js directly on your machine.

​
Quick run

Use this command to start the container interactively and confirm it responds:
The -i flag (interactive / keep stdin open) is required. The container runs a stdio MCP server that reads JSON-RPC messages from standard input. Without -i, Docker closes stdin immediately and the server exits.
The --rm flag removes the container automatically when it exits, keeping your system clean between sessions.
Never pass HEVY_API_KEY as a literal value in a docker run argument visible in your shell. Command-line arguments appear in shell history, process listings (ps aux), and container inspection output. Use -e HEVY_API_KEY to inherit the value from the current environment, or use --env-file with a protected file as shown below.

​
MCP client configuration

MCP clients that support launching a local command (Claude Desktop, Cursor, and others) can start the Docker container directly. Store your key in a protected environment file and reference it with --env-file:
Replace /absolute/path/to/hevy-mcp.env with the actual path to your environment file (see Environment file below). Relative paths are not reliable here because MCP clients may launch the process from a different working directory.
For Claude Desktop specifically, place this config in:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Then restart Claude Desktop for the change to take effect.

​
Environment file

Create a plain-text file containing your Hevy API key. Store it outside of any version-controlled directory and restrict its permissions:
Set restrictive file permissions so other users on the machine cannot read it:
Pass the file to Docker with --env-file /absolute/path/to/hevy-mcp.env. Docker reads the file at container start; the key is injected into the container environment and is never written to any Docker log or layer.
Add hevy-mcp.env to your .gitignore file immediately. A key accidentally committed to a repository — even briefly — should be considered compromised and rotated in the Hevy app settings.

​
Pinning image versions

The latest tag always points to the most recent release. For reproducible environments — CI pipelines, team configs, production deployments — pin an exact semantic version instead:
Pinned example in an MCP client config:
Check the GitHub Container Registry for available tags. Upgrade by updating the tag in your config and restarting your MCP client.

​
Next steps

Hosted Endpoint

Skip Docker entirely — connect directly to the Cloudflare Worker with a bearer token. No local process needed.

Claude Desktop

Full setup guide for Claude Desktop on macOS and Windows, including the Docker command config.

Security Guide

Best practices for managing your Hevy API key across local and hosted deployment modes.

Troubleshooting

Diagnose container startup failures, authentication errors, and client configuration issues.