Hevy MCP Server

Hevy MCP Server

Hevy CLI

Prefer the terminal? The separate @chrisdoc/hevy-cli package reads workouts, routines, exercises, and body measurements directly from the Hevy API, and can create or update those resources with explicit confirmation. Deletion is not supported.

npm install -g @chrisdoc/hevy-cliexport HEVY_API_KEY=your-hevy-api-key
hevy workouts list --page-size 10hevy summary --weeks 4

Add --json to any command for scripts and pipelines. The CLI is a standalone Hevy API client, not an MCP wrapper. See packages/cli/README.md for the full command reference, pagination behavior, and exit codes.

hevy-mcp is an open-source Model Context Protocol (MCP) server for the Hevy fitness and workout tracking app. It lets AI assistants read, analyze, create, and update your Hevy workouts, routines, exercise templates, and body measurements through authenticated Hevy API requests.

The Node stdio/HTTP adapter and Cloudflare Worker share the same MCP tools. See deployment modes to choose a transport, or architecture for workspace ownership, runtime scopes, and supported embedding APIs.

A Hevy API key, available with Hevy PRO, is required.

See it in action

[Hevy MCP demo showing an AI assistant analyzing six weeks of Hevy training data]

_{Click the preview to play the full-quality 18-second demo.}

In the demo, the assistant retrieves real Hevy data and answers a multi-part training question with evidence from the user's workout history.

What can you do with it?

• Analyze training progress: summarize 1-12 weeks of workouts and body measurements in one tool call.
• Ask questions in plain language: find recent sessions, frequently trained exercises, consistency gaps, routine details, or exercise history.
• Plan and log training: create or update workouts, routines, routine folders, custom exercises, and body measurements.
• Search without huge responses: discover routines and exercise templates with compact, AI-friendly results.
• Connect from your preferred MCP client: use the hosted Streamable HTTP endpoint or run locally with Codex, Claude Desktop, Cursor, and other clients.
• Start without installing anything: connect directly to the production Cloudflare Worker—no Node.js, package download, or Docker container required.
• Keep local control when you want it: run the same server with npx, bunx, or the official Docker image.

Try asking:

Analyze my training over the last six weeks. Show workouts per week, my most frequently trained exercises, any obvious gaps or inconsistencies, and cite the workout evidence you used.

Find my push-day routine and show its exercises and sets.

Compare my recent body measurements with my training consistency.

Create a completed workout from my saved routine. Ask me for any missing set results before writing it to Hevy.

Claude integration

The repository includes a Claude plugin that connects to the hosted OAuth-enabled MCP endpoint without embedding a user's Hevy API key.

Claude.ai and Claude Desktop

In Claude, open Settings → Connectors → Add custom connector and enter:

https://mcp.hevy-mcp.dev/mcp

Complete the OAuth flow and enter the Hevy API key when prompted. The same remote endpoint can be used by Claude Desktop and other clients that support remote MCP connectors.

Claude Code and Cowork

The Claude plugin is defined by .claude-plugin/plugin.json and .mcp.json. Install it from this public repository or from the Claude Plugin Directory after publication. It adds the hosted Hevy MCP connector and the Hevy workout skill.

See the privacy policy for the hosted service's data handling details.

Quick start

1. Get your Hevy API key

Create an API key in Hevy's API settings, then keep it somewhere secure. API access currently requires a Hevy PRO subscription.

2. Connect hevy-mcp to your client

The hosted Cloudflare endpoint is the fastest way to start. It runs remotely, so your client does not need Node.js, Bun, Docker, or a local server process.

Connect to the hosted endpoint

Production URL:

https://mcp.hevy-mcp.dev/mcp

The endpoint uses Streamable HTTP. Send your Hevy API key as a bearer token on every request.

Codex

Codex CLI, the Codex desktop app, and the IDE extension share the same MCP configuration. Make your Hevy API key available in the environment that starts Codex, then add the hosted server:

export HEVY_API_KEY=your-hevy-api-keycodex mcp add hevy \  --url https://mcp.hevy-mcp.dev/mcp \  --bearer-token-env-var HEVY_API_KEY

Codex stores the environment variable name, not the key itself, in its MCP configuration. Restart Codex or begin a new session, then run codex mcp list to verify the server is configured.

Other Streamable HTTP clients

Clients that accept a remote MCP URL and fixed headers commonly use this shape:

{	"mcpServers": {		"hevy": {			"url": "https://mcp.hevy-mcp.dev/mcp",			"headers": {				"Authorization": "Bearer your-hevy-api-key"			}		}	}}

Exact configuration keys vary by client. The hosted server requires support for Streamable HTTP and a fixed Authorization header.

[!IMPORTANT] Treat the bearer value like a password. The Worker validates it with Hevy for each request, does not store it, and forwards it to Hevy only as the required api-key header.

Run locally instead

Choose local stdio if you prefer to run the server on your own machine or your client cannot attach a fixed authorization header to remote MCP requests.

Codex

codex mcp add hevy \  --env HEVY_API_KEY=your-hevy-api-key \  -- npx -y hevy-mcp

Claude Desktop or Cursor

Add this mcpServers entry to your client configuration:

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

Google Antigravity

There are two ways to configure the Hevy MCP server for Google Antigravity (agy):

Option A: Automatic Plugin Installation (Recommended)

This utilizes the built-in plugin system:

The plugin reads the repository-root mcp_config.json to start the local stdio server. That configuration intentionally contains no API key; the server inherits HEVY_API_KEY from the host environment as described below. This is separate from the manual, user-global configuration described below and from the repository's .mcp.json, which configures hosted HTTP/OAuth.

1. Install the plugin:

   bash

   agy plugin install https://github.com/chrisdoc/hevy-mcp

2. Provide the HEVY_API_KEY in your host shell environment so the CLI child process can inherit it:

   • Persistent: Save the environment variable HEVY_API_KEY in your system/shell configurations:
     • macOS / Linux: Add it to your shell profile configurations (e.g., ~/.zshrc or ~/.bashrc):
       bash

       export HEVY_API_KEY="your-actual-api-key"

     • Windows: Add it to your User or System Environment Variables. In PowerShell, you can run:
       powershell

       [Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")

   • Temporary (Session-only): If you do not want to persist the key, export it in your active terminal session before running agy:
     bash

     export HEVY_API_KEY="your-actual-api-key"

Option B: Manual Configuration (No Plugin)

If you prefer configuring it statically via the global configuration file:

1. Open your global MCP configuration file:

   • Location: ~/.gemini/config/mcp_config.json

2. Add the hevy configuration block under the mcpServers key. Make sure to merge this entry with any existing servers you have configured rather than replacing the entire file contents:

   json

   {	"mcpServers": {		"hevy": {			"command": "npx",			"args": ["-y", "hevy-mcp"],			"env": {				"HEVY_API_KEY": "your-actual-api-key"			}		}	}}

Common local configuration 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

Restart or reconnect the client after saving the file.

Any stdio MCP client

Configure your client to launch this command with HEVY_API_KEY in the child process environment:

npx -y hevy-mcp

npx requires Node.js 20 or newer. Restart or reconnect your client after saving its configuration.

{	"mcpServers": {		"hevy": {			"command": "bunx",			"args": ["hevy-mcp@latest"],			"env": {				"HEVY_API_KEY": "your-hevy-api-key"			}		}	}}

export HEVY_API_KEY=your-hevy-api-keydocker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

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

You can also add the npm server to supported clients with add-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

3. Ask your first question

Try one of these after restarting or reconnecting your MCP client:

• “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 ask for approval before mutation tools when the client supports tool confirmations.

How it works

Hosted:  Your AI assistant  →  Streamable HTTP  →  Cloudflare Worker  →  Hevy APILocal:   Your AI assistant  →  MCP over stdio   →  local hevy-mcp     →  Hevy API

The hosted endpoint creates a fresh MCP server and Hevy client for each request. Direct bearer authentication uses the supplied Hevy key and caches successful validation for 15 minutes without persisting the raw key. OAuth instead stores the key encrypted in a grant. Neither path creates a shared MCP user session. The local server follows the same tool contract but receives the Hevy key through its process environment.

In either mode, read tools retrieve data; mutation tools create or replace data only when your assistant calls them.

Guided prompts

These server-provided MCP prompts coordinate common multi-step workflows:

Tools

hevy-mcp registers 23 tools. Read-only tools are safe for exploration; create and update tools are exposed with MCP mutation annotations so compatible clients can request confirmation.

| Workouts | get-workout-events | List workout update and delete events since a timestamp. | | Workouts | create-workout | Create a completed workout in Hevy. | | Workouts | update-workout | Patch workout metadata by ID; is_private is required, while other omitted fields and all exercises remain unchanged. | | Workouts | replace-workout-exercises | Replace all exercises and sets; is_private is required and updated, while other workout metadata remains unchanged. | | Routines | search-routines | Search routine titles and return compact metadata for discovery. | | Routines | get-routines | List custom and default workout routines. | | Routines | get-routine | Get one routine and its exercise configuration by ID. | | Routines | create-routine | Create a reusable workout routine. | | Routines | update-routine | Replace an existing routine's content. |

| Routine folders | get-routine-folder | Get one routine folder's metadata by ID. | | Routine folders | create-routine-folder | Create a routine folder. |

| Exercise templates | get-exercise-template | Get complete metadata for one exercise template by ID. | | Exercise templates | search-exercise-templates | Search the full exercise catalog by title substring. | | Exercise templates | create-exercise-template | Create a custom exercise template. | | Exercise history | get-exercise-history | Get past performed sets for one exercise template. | | Body measurements | get-body-measurements | List dated body measurements. | | Body measurements | get-body-measurement | Get the body measurement entry for one date. | | Body measurements | create-body-measurement | Create a dated body measurement. | | Body measurements | update-body-measurement | Update the body measurement for an existing date. | | Diagnostics | feedback | Report a concise, privacy-safe description of an issue or unexpected behavior. |

create-routine and update-routine require a top-level routine envelope with a non-empty exercises array; each exercise must contain at least one set, and fields use snake_case at every level:

{	"routine": {		"title": "Full Body A",		"folder_id": 123,		"notes": "First four exercises are the minimum viable workout",		"exercises": [			{				"exercise_template_id": "30E293E3",				"superset_id": null,				"rest_seconds": 120,				"notes": "Controlled active ROM",				"sets": [					{						"type": "normal",						"rep_range": {							"start": 6,							"end": 10						}					}				]			}		]	}}

The Hevy API currently exposes no delete endpoints for workouts, routines, routine folders, exercise templates, or body measurements, so there are no corresponding delete tools.

Resources

Hosted Cloudflare endpoint

The production MCP server is live at:

https://mcp.hevy-mcp.dev/mcp

It is the quickest way to use hevy-mcp: there is nothing to install or keep running locally, and it exposes the same 23 tools as the npm package and Docker image.

The Cloudflare Worker uses stateless Streamable HTTP at POST /mcp. Clients must send their Hevy API key as a fixed authorization header:

{	"mcpServers": {		"hevy": {			"url": "https://mcp.hevy-mcp.dev/mcp",			"headers": {				"Authorization": "Bearer your-hevy-api-key"			}		}	}}

In this configuration the bearer value is your Hevy API key, not an OAuth token. The Worker caches successful validation for 15 minutes under a hashed key, does not persist the raw key on this direct path, and forwards it upstream only as Hevy's required api-key header.

OAuth for Claude.ai and other remote MCP clients

The hosted production Worker is deployed with an OAUTH_KV namespace binding, so it exposes a full OAuth 2.1 layer for clients that cannot send a fixed header, such as Claude.ai custom connectors. Self-hosted Workers can opt in by following the OAUTH_KV setup in CONTRIBUTING.md:

• RFC 8414 / RFC 9728 discovery metadata under /.well-known/
• Client ID Metadata Documents (CIMD), with dynamic client registration (/register) as a fallback, and PKCE token exchange (/token)
• An /authorize page where you paste your Hevy API key once; the key is validated with Hevy and stored encrypted inside the OAuth grant

Add the Worker URL ending in /mcp as a Claude.ai custom connector and complete the authorization flow in the browser. Direct Authorization: Bearer <hevy-api-key> requests keep working unchanged — the OAuth layer is purely additive. Revoking or rotating your Hevy key prevents subsequent Hevy API access with that key; it does not itself delete stored grants or immediately clear cached validation.

OAuth access tokens last seven days and refresh tokens last 30 days. This reduces KV writes from frequent hourly refreshes while preserving automatic refresh for supported clients.

The endpoint does not expose legacy SSE or a GET event stream. Without the opt-in OAuth layer, clients that require OAuth discovery, dynamic registration, CIMD, or token refresh are not compatible unless they can send the fixed custom header above.

Self-host the Worker

A clean clone can deploy the portable TypeScript Cloudflare configuration with pnpm --dir packages/worker exec cf deploy and receive a workers.dev URL. OAuth requires your own OAUTH_KV namespace; custom domains, routes, and observability destinations are optional account-owned settings. See CONTRIBUTING.md for setup and for the distinction between self-hosting and the maintainer-only named environments.

See CONTRIBUTING.md to deploy the Cloudflare Worker for self-hosted Streamable HTTP.

Advanced configuration

The local Node executable uses stdio by default. Opt into local Streamable HTTP with:

HEVY_API_KEY=your-hevy-api-key npx hevy-mcp --transport http --host 127.0.0.1 --port 3000

The local MCP endpoint is http://127.0.0.1:3000/mcp; non-loopback binds require the separate HEVY_MCP_HTTP_BEARER_TOKEN environment variable. A Docker deployment must publish the port explicitly:

docker run --rm -p 3000:3000 -e HEVY_API_KEY -e HEVY_MCP_HTTP_BEARER_TOKEN \\  ghcr.io/chrisdoc/hevy-mcp:latest --transport http --host 0.0.0.0 --port 3000

This Node HTTP mode is distinct from the stateless Cloudflare Worker HTTP endpoint described above: the Node server owns stateful client sessions, while the Worker is designed for hosted deployment and does not import Node code.

Cache behavior

search-exercise-templates and hevy://exercise-templates share a server-scoped in-memory catalog cache:

• Entries live for five minutes, and the cache holds at most one catalog.
• Concurrent catalog requests share an in-flight fetch when possible.
• search-exercise-templates accepts refresh: true to invalidate the cache.
• Each hosted Worker request gets a fresh catalog cache, preventing cross-key sharing.
• Each local HTTP session owns its own MCP server and catalog cache; caches are not shared across sessions.

Local Node telemetry and privacy

Published Node builds enable project telemetry by default. Unbuilt source runs (such as development and probe scripts) disable it unless HEVY_MCP_TELEMETRY=1 is set explicitly. This is local Node behavior only; the Cloudflare Worker does not import Node telemetry. Set HEVY_MCP_TELEMETRY=0 before launching Node to disable all project telemetry in either mode. In published builds, every value except the literal 0 retains the enabled default. The scoped Node lifecycle Layer acquires telemetry; importing the package remains side-effect-free. Enabled source runs use the Sentry environment development; published builds use production. Set SENTRY_ENVIRONMENT to override this label, for example to qa or staging. The master setting takes precedence over SENTRY_DSN and packaged or runtime OTEL_COLLECTOR_TOKEN credentials, so the disabled path creates no telemetry exporters or periodic metric readers and makes no telemetry network requests. SENTRY_DSN remains a Sentry-only setting; when telemetry is enabled, an empty value disables only Sentry export.

When enabled, actionable errors are sent to the Sentry project configured by SENTRY_DSN; Sentry performance tracing is disabled. Exception messages and stacks are bounded and scrubbed before export. Set HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 to keep structural traces and metrics while suppressing those details. Traces and metrics continue to be sent to the collector at https://otel.chrisdoc.dev/v1/traces and https://otel.chrisdoc.dev/v1/metrics. The project uses its own OpenTelemetry Collector; downstream destinations are configured in that infrastructure. Metrics export every 30 seconds. See observability documentation for Cloudflare OTLP export and domain tracing.

The raw API key is never exported. Ordinary tool telemetry can include a short, deterministic HMAC pseudonym derived from the key for correlation; feedback uses a separate unobserved path. A per-failure diagnostic ID and OTel trace ID may be attached to actionable errors. See telemetry data dictionary for the bounded telemetry fields and privacy contract.

Exception messages and stacks are treated as diagnostic details: they are length-limited, scrubbed for credentials, URLs, and local home paths, and removed entirely when HEVY_MCP_TELEMETRY_DIAGNOSTICS=0. Prompts, tool arguments, tool results, request bodies, API keys, raw identifiers/queries, exact dates, workout/routine/folder/template/body-measurement content, names/titles/descriptions/notes, measurement values, arbitrary client metadata, and unnormalized endpoint paths remain prohibited.

Security and mutations

• Keep HEVY_API_KEY out of source control, URLs, logs, and screenshots.
• Local clients provide the key through the child process environment.
• Direct hosted clients send the Hevy key only in the Authorization: Bearer header; successful validation is cached, but the raw key is not persisted. OAuth grants store the key encrypted. Both paths send it to Hevy only as the api-key header.
• Browser MCP requests must be same-origin or match an exact allowlisted origin. The default allowlist includes Claude.ai, ChatGPT, VS Code for the Web, and github.dev; self-hosted deployments can override it with MCP_ALLOWED_ORIGINS. See deployment modes for the OAuth authorization-form exception.
• Local development can copy .dev.vars.example to .dev.vars to disable Origin validation for MCP Inspector. PR preview Workers use the same development-only setting because their browser origins are dynamic. Never set MCP_DISABLE_ORIGIN_CHECK=true on a production Worker.
• Create operations can produce duplicates when retried. Routine updates replace content; workout metadata updates preserve omitted fields and exercises, while replace-workout-exercises replaces all exercises and sets. Review tool inputs and use client confirmations.

Troubleshooting

• The server does not appear: restart or reconnect your MCP client after changing its configuration.
• npx fails: confirm that Node.js 20 or newer is installed, then run npx -y hevy-mcp --version in a terminal.
• Codex cannot see the server: run codex mcp list, then start a new Codex session after confirming the hevy entry exists.
• Hevy API returns 401: the key is invalid, expired, revoked, or misconfigured. Verify or create an active key at Hevy's API settings, then restart the client.
• Hosted authentication fails: confirm the key belongs to a Hevy PRO account and is sent as Authorization: Bearer <HEVY_API_KEY>.
• Local authentication fails: confirm the key is active and available to the MCP child process as HEVY_API_KEY.
• Need diagnostics: set HEVY_MCP_DEBUG=1. Diagnostic output goes to stderr and does not interfere with MCP messages on stdout.

If you find a bug or have a feature request, open an issue.

Contributing

Contributions are welcome. Developer setup, testing lanes, generated-client workflows, Cloudflare Worker deployment, and pull request rules are documented in CONTRIBUTING.md.

Use mise for the pinned Node.js and pnpm versions, then run the deterministic unit lane. It does not need a live Hevy API key:

MISE_AUTO_INSTALL=false mise installMISE_AUTO_INSTALL=false mise exec -- pnpm installMISE_AUTO_INSTALL=false mise exec -- pnpm run test:unit

License and acknowledgements

• License: MIT
• Credits: Model Context Protocol and Hevy Fitness