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

# Get started with Hevy MCP in minutes

> Connect your first MCP client to Hevy in under five minutes using the hosted Cloudflare endpoint or a local npx server. No Docker required.

Hevy MCP offers two connection paths. The **hosted endpoint** at `https://hevy.chrisdoc.dev/mcp` is the fastest way to start — nothing to install, nothing to keep running, just point your client at the URL and send your API key as a bearer token. The **local stdio** path runs the server as a child process on your own machine via `npx`, giving you full local control and working with clients that cannot attach a fixed authorization header to remote requests.

<Note>
  The local `npx` path requires **Node.js 20 or newer**. Run `node --version` to confirm before proceeding. The hosted endpoint has no local dependency requirements.
</Note>

<Steps>
  <Step title="Get your Hevy API key">
    Open the **Hevy app**, navigate to **Settings → Account**, and generate an API key. Copy it and store it somewhere secure — treat it like a password.

    API access requires an active **Hevy PRO** subscription. If you do not see the API key option in settings, confirm that your PRO subscription is active.

    You will supply this key to your MCP client in the next step. Never put it in source control, a URL, a log file, or a CLI argument.
  </Step>

  <Step title="Choose your connection method">
    <Tabs>
      <Tab title="Hosted Endpoint">
        The hosted Cloudflare Worker is live at `https://hevy.chrisdoc.dev/mcp` and uses Streamable HTTP. Your client must be able to attach a fixed `Authorization` header to every MCP request.

        Add the following to your MCP client's server configuration, replacing `your-hevy-api-key` with the key you copied in step 1:

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

        The bearer value is your Hevy API key, not an OAuth token. The Worker validates it with Hevy on each request, does not store it, and forwards it upstream only as Hevy's required `api-key` header.

        After saving your client configuration, restart or reconnect the client to pick up the new server.
      </Tab>

      <Tab title="Local (npx)">
        The local server runs as a stdio child process launched by your MCP client. Node.js 20+ is required.

        The command your client will execute is:

        ```bash theme={null}
        npx -y hevy-mcp
        ```

        Add the following `mcpServers` entry to your client configuration, replacing `your-hevy-api-key` with the key you copied in step 1:

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

        Common configuration file locations:

        * **Claude Desktop on macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Claude Desktop on Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
        * **Cursor:** `~/.cursor/mcp.json`

        After saving the file, restart or reconnect your client.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Ask your first question">
    Once your client has reconnected and the `hevy` server appears in its MCP server list, try one of these prompts:

    * *"Give me a training summary for the last four weeks."*
    * *"What routines do I have saved on Hevy?"*
    * *"Show my three most recent workouts."*
    * *"Find exercise templates containing squat."*
    * *"Which Hevy account is connected?"*

    Your assistant should request approval before running any mutation tools (create or update) when the client supports tool confirmations. Read-only tools like summaries and searches are safe to run without confirmation.
  </Step>
</Steps>

For client-specific setup instructions — including Codex CLI, Claude Desktop, and the Docker image — see [Clients: Hosted Endpoint](/hevy-mcp/clients/hosted-endpoint).