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

# Connect Claude Desktop to Hevy MCP

> Add Hevy MCP to Claude Desktop on macOS or Windows using npx for local stdio or the hosted Cloudflare endpoint for remote access.

Claude Desktop supports stdio MCP servers through an `mcpServers` configuration block. Add the `hevy` entry to your Claude Desktop config file, save it, restart the app, and Claude gains access to all 25 Hevy MCP tools in every conversation.

<Note>
  `npx` requires **Node.js 20 or newer**. Run `node --version` in a terminal to
  confirm before proceeding.
</Note>

## Using npx (local stdio)

The local stdio approach runs `hevy-mcp` as a child process on your machine. Claude Desktop manages the process lifetime automatically; you do not need to start or stop it manually.

<Steps>
  <Step title="Open your Claude Desktop config file">
    The configuration file location depends on your operating system:

    <Tabs>
      <Tab title="macOS">
        ```text theme={null}
        ~/Library/Application Support/Claude/claude_desktop_config.json
        ```

        Open it in any text editor. If the file does not exist yet, create it.
      </Tab>

      <Tab title="Windows">
        ```text theme={null}
        %APPDATA%\Claude\claude_desktop_config.json
        ```

        Paste the path into File Explorer's address bar or open it in Notepad.
        If the file does not exist yet, create it.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the hevy-mcp server entry">
    Merge the following `mcpServers` block into your config. If the file is
    empty, paste the entire object; if it already contains other servers, add
    the `hevy` key alongside them.

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

    Replace `your-hevy-api-key` with the key from your Hevy app settings.
  </Step>

  <Step title="Save and restart Claude Desktop">
    Save the config file, then fully quit and reopen Claude Desktop. The MCP
    server is registered at startup; changes to the config file take effect
    only after a restart.
  </Step>
</Steps>

<Note>
  Restart Claude Desktop after every change to `claude_desktop_config.json`.
  The app reads the file once at launch and does not watch it for live changes.
</Note>

## Using the hosted endpoint

The hosted Cloudflare Worker at `https://hevy.chrisdoc.dev/mcp` requires no local Node.js installation. There are two ways to connect Claude to it.

<Tabs>
  <Tab title="Claude.ai custom connector (OAuth)">
    Claude.ai (the web app) supports adding remote MCP servers through its
    Integrations settings. The hosted endpoint implements a full OAuth 2.1
    flow with PKCE so Claude.ai can authenticate without you manually
    managing a bearer token.

    1. Open **Claude.ai → Settings → Integrations → Add custom connector**.
    2. Enter `https://hevy.chrisdoc.dev/mcp` as the server URL.
    3. Complete the browser authorization page that appears — paste your Hevy
       API key when prompted.

    See the [Hosted Endpoint](/hevy-mcp/clients/hosted-endpoint) page for a full
    walkthrough of the OAuth discovery and PKCE exchange flow.
  </Tab>

  <Tab title="Direct bearer header (Desktop)">
    If your version of Claude Desktop supports a `url` + `headers` config
    shape for remote MCP servers, you can point it directly at the hosted
    endpoint with a fixed bearer token:

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

    Replace `your-hevy-api-key` with your actual key. This config does not
    require Node.js or any local process.
  </Tab>
</Tabs>

## Verify the connection

After restarting Claude Desktop, start a new conversation and ask:

> Which Hevy account is connected?

Claude will call the `get-user-info` tool and respond with your Hevy display name and profile URL. If it responds without invoking a tool, the server is not connected — double-check the config file path and JSON syntax, then restart again.

<Tip>
  You can also ask "What tools do you have available?" to see the full list of
  25 Hevy MCP tools Claude can use.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted Endpoint" icon="cloud" href="/hevy-mcp/clients/hosted-endpoint">
    Learn how the Cloudflare Worker handles authentication and the OAuth 2.1
    layer for Claude.ai connectors.
  </Card>

  <Card title="Guided Prompts" icon="message-square" href="/hevy-mcp/guides/prompts">
    Use server-provided MCP prompts to kick off multi-step workflows like
    training analysis and workout logging.
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/hevy-mcp/tools/overview">
    Browse all 25 tools available to Claude once hevy-mcp is connected.
  </Card>

  <Card title="Troubleshooting" icon="circle-alert" href="/hevy-mcp/guides/troubleshooting">
    Steps to diagnose missing servers, authentication failures, and npx errors.
  </Card>
</CardGroup>