> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chrisdoc.dev/hevy-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Hevy MCP with Docker

> Pull the official Hevy MCP Docker image for linux/amd64 and linux/arm64, run it as a local stdio MCP server, and configure any MCP client to use it.

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:

```bash theme={null}
export HEVY_API_KEY=your-hevy-api-key
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest
```

<Note>
  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.
</Note>

The `--rm` flag removes the container automatically when it exits, keeping your system clean between sessions.

<Warning>
  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.
</Warning>

## 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`:

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

Replace `/absolute/path/to/hevy-mcp.env` with the actual path to your environment file (see [Environment file](#environment-file) below). Relative paths are not reliable here because MCP clients may launch the process from a different working directory.

<Note>
  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.
</Note>

## Environment file

Create a plain-text file containing your Hevy API key. Store it outside of any version-controlled directory and restrict its permissions:

```bash theme={null}
# hevy-mcp.env
HEVY_API_KEY=your-hevy-api-key
```

Set restrictive file permissions so other users on the machine cannot read it:

```bash theme={null}
chmod 600 /absolute/path/to/hevy-mcp.env
```

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.

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
ghcr.io/chrisdoc/hevy-mcp:X.Y.Z
```

Pinned example in an MCP client config:

```json theme={null}
{
  "mcpServers": {
    "hevy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/hevy-mcp.env",
        "ghcr.io/chrisdoc/hevy-mcp:1.0.0"
      ]
    }
  }
}
```

Check the [GitHub Container Registry](https://github.com/chrisdoc/hevy-mcp/pkgs/container/hevy-mcp) for available tags. Upgrade by updating the tag in your config and restarting your MCP client.

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted Endpoint" icon="cloud" href="/hevy-mcp/clients/hosted-endpoint">
    Skip Docker entirely — connect directly to the Cloudflare Worker with a
    bearer token. No local process needed.
  </Card>

  <Card title="Claude Desktop" icon="message-circle" href="/hevy-mcp/clients/claude-desktop">
    Full setup guide for Claude Desktop on macOS and Windows, including the
    Docker command config.
  </Card>

  <Card title="Security Guide" icon="shield" href="/hevy-mcp/guides/security">
    Best practices for managing your Hevy API key across local and hosted
    deployment modes.
  </Card>

  <Card title="Troubleshooting" icon="circle-alert" href="/hevy-mcp/guides/troubleshooting">
    Diagnose container startup failures, authentication errors, and client
    configuration issues.
  </Card>
</CardGroup>