Hevy MCP

A guarded Model Context Protocol server for the official Hevy fitness API.

What it exposes

Read tools:

• list_workouts

• get_workout

• list_routines

• get_routine

• search_exercise_templates

• get_exercise_history

Write tools:

• create_routine

• update_routine

• create_workout

Write tools are disabled by default and require the exact tool argument confirmation="CONFIRM" after the final payload has been reviewed.

Related MCP server: hevy-mcp-server

Important Hevy constraints

• Hevy API access currently requires Hevy Pro and an API key.

• The API is marked early-stage, so endpoint/schema changes are possible.

• The official API currently has no general delete operations for the supported entities.

• A Hevy API key must never be placed in a prompt, tool argument, URL, log, screenshot, source repository, or Docker image.

Architecture

MCP client
   |
   | stdio, or HTTPS Streamable HTTP
   v
Hevy MCP
   |
   | api-key header
   v
Official Hevy API

The server is stateless. In shared HTTP mode, each caller supplies their own Hevy key in the X-Hevy-API-Key transport header. The key is held only for the request and forwarded to Hevy as api-key.

For a serious public service, replace raw per-request Hevy keys with an OAuth login plus an encrypted credential vault. Do not operate a giant shared secret spreadsheet. Humanity has tested that architecture thoroughly.

Local setup

Requirements:

• Python 3.11+

• Hevy Pro

• Hevy API key from Hevy's developer settings

cp .env.example .env
# Set HEVY_API_KEY in .env
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
hevy-mcp

The default transport is stdio.

Example local client configuration:

{
  "mcpServers": {
    "hevy": {
      "command": "/absolute/path/hevy-mcp/.venv/bin/hevy-mcp",
      "env": {
        "HEVY_API_KEY": "YOUR_KEY",
        "MCP_TRANSPORT": "stdio",
        "ALLOW_WRITES": "false"
      }
    }
  }
}

Keep the key in your client's secret/environment facility where available.

Test with MCP Inspector

For HTTP mode:

MCP_TRANSPORT=streamable-http \
HEVY_API_KEY="$HEVY_API_KEY" \
MCP_ACCESS_TOKEN="$(openssl rand -hex 32)" \
hevy-mcp

Connect Inspector to:

http://localhost:8000/mcp

Send the configured bearer token in Authorization.

Docker deployment

cp .env.example .env

Set at minimum:

MCP_TRANSPORT=streamable-http
HOST=0.0.0.0
PORT=8000
MCP_ACCESS_TOKEN=<long-random-token>
ALLOW_HEADER_HEVY_KEY=true
ALLOW_WRITES=false

Then:

docker compose up -d --build
curl http://localhost:8000/health

The container:

• runs as a non-root user

• uses a read-only filesystem

• drops Linux capabilities

• enables no-new-privileges

• includes a health check

Make it safely usable by other people

Small trusted group

Deploy behind an HTTPS reverse proxy and require:

• a unique gateway token per environment, preferably per user

• X-Hevy-API-Key supplied by each user's MCP client

• strict origin allowlisting if browser clients are supported

• rate limiting at the proxy and application

• access logs with secrets redacted

• ALLOW_WRITES=false until mutation workflows are reviewed

Example headers:

Authorization: Bearer <your-mcp-gateway-token>
X-Hevy-API-Key: <the-user's-hevy-key>

Public production service

Do not ask users to hand a permanent Hevy API key to your website without a proper credential system. Build:

1. User login with OAuth/OIDC for your service.

2. Encrypted per-user secret storage using KMS or a managed secret vault.

3. Short-lived MCP access tokens bound to user and tenant.

4. Server-side retrieval of the correct Hevy key after authentication.

5. Per-tool authorization scopes such as hevy:read and hevy:write.

6. Explicit approval UI for mutations.

7. Audit records containing user, tool, target ID, timestamp, and result, but no secret.

8. Revocation, account deletion, key rotation, abuse detection, and privacy controls.

MCP recommends OAuth for remote authorization. A raw bearer gateway token is included here as a deployable baseline, not as the final identity system for a consumer SaaS.

Reverse proxy example with Caddy

mcp.example.com {
    reverse_proxy hevy-mcp:8000
    encode zstd gzip

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "no-referrer"
    }
}

Caddy provisions TLS automatically when DNS points to the server and ports 80/443 are open.

Cloud deployment outline

The Docker image can run on:

• Google Cloud Run

• AWS ECS/Fargate

• Azure Container Apps

• Fly.io

• Render

• a VM with Docker and Caddy

• Kubernetes

Minimum production configuration:

• HTTPS only

• secrets from the cloud secret manager, never image/environment files committed to Git

• at least two instances only after moving rate limiting to Redis or the gateway

• bounded request/body sizes

• outbound egress restricted to api.hevyapp.com

• alerting on authentication failures, 429s, and upstream errors

• dependency and container scanning

• pinned image digests and a rollback path

Guardrails implemented

• Read/write separation

• writes disabled by default

• exact confirmation token for every mutation

• typed bounds for weight, reps, time, distance, notes, and object counts

• no delete or arbitrary HTTP tools

• no arbitrary shell, SQL, file, or URL access

• no secret accepted as an MCP tool argument

• per-request credential context

• rate limiting

• bounded page sizes

• timeouts and safe retries only for GET operations

• structured, non-secret errors

• non-root/read-only container

• medical-safety instruction and resource

• idempotency annotation on replacement updates

• warnings that creates may duplicate on retry

Known limitations

• The in-memory limiter is per process. Use a gateway or Redis for multiple replicas.

• The shared-header mode depends on the MCP client supporting custom headers.

• Exact Hevy request schemas may evolve because the upstream API is early-stage.

• update_routine is a replacement operation. Always fetch and review the current routine.

• The project intentionally implements a focused tool set instead of exposing every endpoint. Broad generic API proxy tools are easier to build and much easier to regret.