Hevy MCP Server

An MCP server that gives AI assistants (Claude, etc.) access to your Hevy workout data via the Model Context Protocol.

Supports both Streamable HTTP (for Claude web/mobile/desktop connector UI with OAuth) and SSE (for Claude Desktop config / CLI).

Deploy

Option 1 — Railway (recommended, free tier available)

1. Fork this repo and connect it to a new Railway project

2. In the Railway dashboard, go to your service → Variables and add:

   Variable	Value
   HEVY_API_KEY	Your Hevy API key (from hevy.com/settings?developer)
   MCP_AUTH_TOKEN	A secret token — run openssl rand -hex 32 to generate one
   MCP_TRANSPORT	sse
   SERVER_BASE_URL	Your Railway public URL (set after generating a domain below)

3. Go to Settings → Networking → Generate Domain, enter port 3847, click Generate Domain

4. Copy the generated URL and update SERVER_BASE_URL to match — Railway will redeploy automatically

5. Check Deploy Logs for Hevy MCP server running

Token persistence on Railway: OAuth tokens are stored in DATA_DIR (defaults to /data). On Railway's free tier the filesystem is ephemeral — tokens won't survive redeploys and users will need to re-authorize. To persist tokens, add a Railway volume mounted at /data and set DATA_DIR=/data.

Option 2 — Docker (self-hosted)

git clone https://github.com/karlhsueh/hevyapp-mcp.git
cd hevyapp-mcp
cp .env.example .env
# Edit .env with your values
docker compose up -d

Verify:

curl http://localhost:3847/health
# {"status":"ok","server":"hevyapp-mcp"}

Expose remotely with Cloudflare Tunnel or any reverse proxy pointing at localhost:3847.

The included docker-compose.yml mounts a named volume at /data for OAuth token persistence across container restarts.

Option 3 — Fly.io (free tier available)

1. Install the Fly CLI and run fly auth login

2. From the repo root: fly launch (accept defaults)

3. Set secrets:

   fly secrets set \
     HEVY_API_KEY=your-key \
     MCP_AUTH_TOKEN=your-token \
     MCP_TRANSPORT=sse \
     SERVER_BASE_URL=https://your-app.fly.dev \
     DATA_DIR=/data

4. Add a volume for token persistence:

   fly volumes create mcp_data --size 1

5. Mount the volume by adding to fly.toml:

   [mounts]
     source = "mcp_data"
     destination = "/data"

6. Deploy: fly deploy

Related MCP server: hevy-mcp-server

Connect to Claude

Claude web / mobile / desktop (connector UI) — OAuth

The server implements OAuth 2.0 so Claude can authenticate without any config files.

1. In Claude, open Settings → Integrations (web/mobile) or Preferences → Integrations (desktop)

2. Click Add custom integration

3. Enter your server URL (e.g. https://your-app.up.railway.app)

4. Claude opens a browser window — enter your MCP_AUTH_TOKEN

5. Done

Claude Desktop (config file)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hevy": {
      "type": "sse",
      "url": "https://your-server/sse",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add hevy --transport sse https://your-server/sse \
  --header "Authorization: Bearer your-secret-token"

Available tools

Updating

git pull
docker compose up -d --build

Logs

docker compose logs -f hevyapp-mcp