Hevy MCP Server

Name: Hevy MCP Server
Author: Christoph Kieslich

Read, analyse and log workouts, routines and body measurements in the Hevy fitness app

By Christoph Kieslich (individual) TypeScript Remote (hosted) · Streamable HTTP Local · stdio Data and analytics Productivity

GitHub npm Website

62 popularity score ★ 533 ↓ 2.5k/wk

Connect your client

Remote (hosted)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude (desktop and web)Settings → Connectors → Add custom connector; finish the OAuth flow and paste the Hevy API key

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

Codexshell, with HEVY_API_KEY exported

codex mcp add hevy \
  --url https://mcp.hevy-mcp.dev/mcp \
  --bearer-token-env-var HEVY_API_KEY

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs HEVY_API_KEY. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add hevy -e HEVY_API_KEY=<HEVY_API_KEY> -- npx -y hevy-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": [
        "-y",
        "hevy-mcp"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": [
        "-y",
        "hevy-mcp"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "hevy": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "hevy-mcp"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.hevy]
command = "npx"
args = ["-y", "hevy-mcp"]

[mcp_servers.hevy.env]
HEVY_API_KEY = "<HEVY_API_KEY>"

Gemini CLITerminal

gemini mcp add --scope user -e HEVY_API_KEY=<HEVY_API_KEY> hevy npx -- -y hevy-mcp

Local (container)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs HEVY_API_KEY. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add hevy -e HEVY_API_KEY=<HEVY_API_KEY> -- docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "hevy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HEVY_API_KEY",
        "ghcr.io/chrisdoc/hevy-mcp:latest"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "hevy": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HEVY_API_KEY",
        "ghcr.io/chrisdoc/hevy-mcp:latest"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "hevy": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HEVY_API_KEY",
        "ghcr.io/chrisdoc/hevy-mcp:latest"
      ],
      "env": {
        "HEVY_API_KEY": "<HEVY_API_KEY>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.hevy]
command = "docker"
args = ["run", "-i", "--rm", "-e", "HEVY_API_KEY", "ghcr.io/chrisdoc/hevy-mcp:latest"]

[mcp_servers.hevy.env]
HEVY_API_KEY = "<HEVY_API_KEY>"

Gemini CLITerminal

gemini mcp add --scope user -e HEVY_API_KEY=<HEVY_API_KEY> hevy docker -- run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

Settings 7

`HEVY_API_KEY`	Required: Hevy API key from Hevy's developer settings (needs Hevy PRO).
`HEVY_MCP_TELEMETRY`	Optional: Set to 0 to turn off telemetry, which published builds send by default.
`HEVY_MCP_TELEMETRY_DIAGNOSTICS`	Optional: Set to 0 to keep telemetry but drop exception messages and stacks.
`HEVY_MCP_API_TIMEOUT`	Optional: Hevy API timeout in milliseconds; 60000 by default.
`HEVY_MCP_DEBUG`	Optional: Set to 1 for diagnostics on stderr.
`HEVY_MCP_HTTP_BEARER_TOKEN`	Optional: Separate token required when local HTTP mode binds to a non-loopback host.
`SENTRY_DSN`	Optional: Overrides the packaged Sentry project; an empty value turns off Sentry export.

In a container, a setting goes in with -e NAME=value after docker run.

What it does

hevy-mcp connects an MCP client to a Hevy account through Hevy's public API. Its 23 tools list and fetch workouts, routines, routine folders, exercise templates, past sets for one exercise and dated body measurements. It can also create and update most of these. One tool, get-training-summary, gathers 1 to 12 weeks of workouts and measurement trends in a single call. Two built-in prompts walk through a progress review and logging a finished workout from a saved routine. Four read-only resources expose the user profile, the workout count, the full exercise catalogue and the folder list.

There are three ways to run it. The npm package (or its Docker image) runs on your own machine over stdio, or over local Streamable HTTP with --transport http. The maintainer also runs a hosted Cloudflare Worker at https://mcp.hevy-mcp.dev/mcp. It accepts the Hevy key as a bearer header, or through an OAuth flow for clients such as Claude.ai custom connectors, where the key is pasted once and kept encrypted in the grant.

The tool list also includes feedback. Its description at version 6.1.22 says it sends a free-text report, up to 2,000 characters, to the maintainers through the project's diagnostic telemetry (packages/core/src/feedback-metadata.ts).

What it needs

To run it yourself	Node.js 20+orDocker

A Hevy API key, created in Hevy's developer settings. Hevy only gives API access with a paid Hevy PRO subscription. Running locally with npx needs Node.js 20 or newer; the bunx form needs Bun; the Docker image needs Docker and is built for linux/amd64 and linux/arm64. The hosted endpoint needs nothing installed, but the client must speak Streamable HTTP and either send a fixed Authorization header or support OAuth.

Limits

There are no delete tools, because the Hevy API has no delete endpoints for workouts, routines, folders, templates or measurements. Retrying a create call can make duplicates. update-routine replaces the whole routine, and replace-workout-exercises replaces every exercise and set in a workout. get-workouts returns workouts in the order the API gives them, not by start time. The exercise catalogue is cached in memory for five minutes unless search-exercise-templates is called with refresh: true. The hosted endpoint offers no legacy SSE transport and no GET event stream.

Who it suits

Hevy PRO users who want an assistant to review their training history or to log workouts and plan routines from a chat. If you would rather not install anything, use the hosted endpoint. Your key then passes through the maintainer's Cloudflare Worker on every request, so if you want it to stay on your own machine, run the npm package or Docker image instead. This is a community project, not one published by Hevy. Without a PRO subscription there is no API key, so it cannot be used at all. Writes are limited to create and update; nothing can be deleted through it.

Tools 23

get-training-summary: Summarises 1 to 12 weeks of workouts and body-measurement trends in one call
get-workouts: Lists workouts with their exercises and timings, in API order
get-workout: Fetches one workout in full by ID
get-workout-events: Lists workout updates and deletions since a given time
create-workout: Logs a completed workout
update-workout: Changes a workout's metadata; omitted fields and exercises stay as they are
replace-workout-exercises: Replaces every exercise and set in a workout
search-routines: Finds routines by title and returns short metadata
get-routines: Lists custom and default routines
get-routine: Fetches one routine with its exercise setup
create-routine: Creates a reusable routine
update-routine: Replaces the content of an existing routine
get-routine-folder: Fetches one routine folder's details
create-routine-folder: Creates a routine folder
get-exercise-template: Fetches one exercise template's full details
search-exercise-templates: Searches the exercise catalogue by part of a title
create-exercise-template: Adds a custom exercise
get-exercise-history: Returns past sets performed for one exercise
get-body-measurements: Lists dated body measurements
get-body-measurement: Fetches the measurement entry for one date
create-body-measurement: Records body measurements for a date
update-body-measurement: Changes the measurements stored for an existing date
feedback: Sends a short problem report to the maintainers through telemetry

Popularity

62 popularity score, on our list (the bar is 36)

★ 533 ↓ 2.5k/wk

GitHub stars, whole repository	533	27.2 points
Stars in 30 days	+26	7.2 points
npm downloads, last week	2,507	27.2 points

It lives in the folder packages/node of chrisdoc/hevy-mcp, which holds more than this server. Its stars are the whole repository's, so in the score they never count for more than its own downloads.

Measured 2026-11-07. How the score works.

Where it is published

Code	chrisdoc/hevy-mcp/packages/node ★ 533, the whole repository
npm	hevy-mcp 6.2.1, 2026-10-16, the one the command runs
Container	ghcr.io/chrisdoc/hevy-mcp
Hosted	`https://mcp.hevy-mcp.dev/mcp` Streamable HTTP · OAuth sign-in

What it can reach

Runs	On your machine, or on the maker's servers
Reaches	Your account at a service, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	OAuth sign-in for the hosted endpoint; an API key or token to run it yourself
Licence	MIT (GitHub)
Last code change	2026-11-07

It reaches one Hevy account through the Hevy API, using the user's API key. Its tools can create and update workouts, routines, folders, custom exercises and body measurements, but cannot delete them. Locally the key comes from the HEVY_API_KEY environment variable. The hosted Worker receives the key as a bearer header on each request and caches successful validation for 15 minutes under a hashed key. With OAuth, the key is stored encrypted in the grant. Published npm builds send telemetry by default: errors go to the maintainer's Sentry project and traces and metrics to otel.chrisdoc.dev. The docs say the raw key and workout content are excluded. HEVY_MCP_TELEMETRY=0 turns this off. Local HTTP mode needs a separate bearer token whenever it binds to a non-loopback address.

Over time

GitHub stars, whole repository 533 +26 (+5 %)

533507

9 Oct 20267 Nov 2026

npm downloads a week 2.5k +1.8k (+253 %)

78k179

20 Oct 20257 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 62 −3 (−5 %)

6451

9 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Hevy MCP Server on EveryMCPServer](https://everymcpserver.com/badge/hevy-mcp-server.svg)](https://everymcpserver.com/servers/hevy-mcp-server)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 7

What it does

What it needs

Limits

Who it suits

Tools 23

Similar servers

Smartsheet MCP Server

MCP Linear

Excel MCP Server

PostHog MCP Server

MCP Server for Excel

AFFiNE MCP Server