Skip to content
Back to search

hevy-mcp

Read, analyze, create, and update Hevy workouts, routines, exercises, and body measurements in Claude.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/chrisdoc/hevy-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/chrisdoc/hevy-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chrisdoc--hevy-mcp/badge.svg)](/listings/chrisdoc--hevy-mcp)

HTML

<a href="/listings/chrisdoc--hevy-mcp"><img src="/api/listings/chrisdoc--hevy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Get your Hevy API key

Create an API key in [Hevy's API settings](https://hevy.com/settings?developer), 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-key
codex 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:

   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:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 5 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "hevy-mcp",
  3. "version": "1.0.0",
  4. "description": "Read, analyze, create, and update Hevy workouts, routines, exercises, and body measurements in Claude."
  5. }
README.md · README · 711 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Hevy MCP Server
  2. <div align="center">
  3. **Talk to your Hevy workout data from Claude, Cursor, Codex, and other MCP clients.**
  4. [![npm version](https://img.shields.io/npm/v/hevy-mcp.svg)](https://www.npmjs.com/package/hevy-mcp)
  5. [![npm downloads](https://img.shields.io/npm/dm/hevy-mcp.svg)](https://www.npmjs.com/package/hevy-mcp)
  6. [![Build and Test](https://github.com/chrisdoc/hevy-mcp/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/chrisdoc/hevy-mcp/actions/workflows/build-and-test.yml)
  7. [![Codecov](https://codecov.io/gh/chrisdoc/hevy-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/chrisdoc/hevy-mcp)
  8. [![GitHub stars](https://img.shields.io/github/stars/chrisdoc/hevy-mcp?style=flat)](https://github.com/chrisdoc/hevy-mcp/stargazers)
  9. [![Hosted on Cloudflare](https://img.shields.io/badge/Hosted_on-Cloudflare-F38020?logo=cloudflare&logoColor=white)](#hosted-cloudflare-endpoint)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
  11. [![MCP Toplist](https://mcptoplist.com/badge/io.github.chrisdoc%2Fhevy-mcp.svg)](https://mcptoplist.com/server/io.github.chrisdoc%2Fhevy-mcp)
  12. [Connect to the hosted MCP](#connect-to-the-hosted-endpoint) · [Use the Hevy CLI](#hevy-cli) · [Watch the 18-second demo](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4) · [Explore all 23 tools](#tools) · [Documentation](./docs/index.md)
  13. </div>
  14. ## Hevy CLI
  15. Prefer the terminal? The separate
  16. [`@chrisdoc/hevy-cli`](https://www.npmjs.com/package/@chrisdoc/hevy-cli)
  17. package reads workouts, routines, exercises, and body measurements directly
  18. from the Hevy API, and can create or update those resources with explicit
  19. confirmation. Deletion is not supported.
  20. ```sh
  21. npm install -g @chrisdoc/hevy-cli
  22. export HEVY_API_KEY=your-hevy-api-key
  23. hevy workouts list --page-size 10
  24. hevy summary --weeks 4
  25. ```
  26. Add `--json` to any command for scripts and pipelines. The CLI is a standalone
  27. Hevy API client, not an MCP wrapper. See
  28. [`packages/cli/README.md`](packages/cli/README.md) for the full command
  29. reference, pagination behavior, and exit codes.
  30. `hevy-mcp` is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
  31. server for the [Hevy](https://www.hevyapp.com/) fitness and workout tracking
  32. app. It lets AI assistants read, analyze, create, and update your Hevy workouts,
  33. routines, exercise templates, and body measurements through authenticated Hevy
  34. API requests.
  35. The Node stdio/HTTP adapter and Cloudflare Worker share the same MCP tools.
  36. See [deployment modes](./docs/deployment-modes.md) to choose a transport, or
  37. [architecture](./docs/architecture.md) for workspace ownership, runtime scopes,
  38. and supported embedding APIs.
  39. > A Hevy API key, available with **Hevy PRO**, is required.
  40. ## See it in action
  41. [![Hevy MCP demo showing an AI assistant analyzing six weeks of Hevy training data](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.gif)](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4)
  42. <p align="center"><sub>Click the preview to play the full-quality 18-second demo.</sub></p>
  43. In the demo, the assistant retrieves real Hevy data and answers a multi-part
  44. training question with evidence from the user's workout history.
  45. ## What can you do with it?
  46. - **Analyze training progress:** summarize 1-12 weeks of workouts and body
  47. measurements in one tool call.
  48. - **Ask questions in plain language:** find recent sessions, frequently trained
  49. exercises, consistency gaps, routine details, or exercise history.
  50. - **Plan and log training:** create or update workouts, routines, routine folders,
  51. custom exercises, and body measurements.
  52. - **Search without huge responses:** discover routines and exercise templates with
  53. compact, AI-friendly results.
  54. - **Connect from your preferred MCP client:** use the hosted Streamable HTTP
  55. endpoint or run locally with Codex, Claude Desktop, Cursor, and other clients.
  56. - **Start without installing anything:** connect directly to the production
  57. Cloudflare Worker—no Node.js, package download, or Docker container required.
  58. - **Keep local control when you want it:** run the same server with `npx`, `bunx`,
  59. or the official Docker image.
  60. Try asking:
  61. > Analyze my training over the last six weeks. Show workouts per week, my most
  62. > frequently trained exercises, any obvious gaps or inconsistencies, and cite the
  63. > workout evidence you used.
  64. > Find my push-day routine and show its exercises and sets.
  65. > Compare my recent body measurements with my training consistency.
  66. > Create a completed workout from my saved routine. Ask me for any missing set
  67. > results before writing it to Hevy.
  68. ## Claude integration
  69. The repository includes a Claude plugin that connects to the hosted OAuth-enabled
  70. MCP endpoint without embedding a user's Hevy API key.
  71. ### Claude.ai and Claude Desktop
  72. In Claude, open **Settings → Connectors → Add custom connector** and enter:
  73. ```text
  74. https://mcp.hevy-mcp.dev/mcp
  75. ```
  76. Complete the OAuth flow and enter the Hevy API key when prompted. The same
  77. remote endpoint can be used by Claude Desktop and other clients that support
  78. remote MCP connectors.
  79. ### Claude Code and Cowork
  80. The Claude plugin is defined by [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json)
  81. and [`.mcp.json`](./.mcp.json). Install it from this public repository or from
  82. the Claude Plugin Directory after publication. It adds the hosted Hevy MCP
  83. connector and the [Hevy workout skill](./skills/hevy-workouts/SKILL.md).
  84. See the [privacy policy](./docs/privacy-policy.md) for the hosted service's
  85. data handling details.
  86. ## Quick start
  87. ### 1. Get your Hevy API key
  88. Create an API key in [Hevy's API settings](https://hevy.com/settings?developer), then
  89. keep it somewhere secure. API access currently requires a Hevy PRO subscription.
  90. ### 2. Connect `hevy-mcp` to your client
  91. The hosted Cloudflare endpoint is the fastest way to start. It runs remotely,
  92. so your client does not need Node.js, Bun, Docker, or a local server process.
  93. #### Connect to the hosted endpoint
  94. Production URL:
  95. ```text
  96. https://mcp.hevy-mcp.dev/mcp
  97. ```
  98. The endpoint uses Streamable HTTP. Send your Hevy API key as a bearer token on
  99. every request.
  100. ##### Codex
  101. Codex CLI, the Codex desktop app, and the IDE extension share the same MCP
  102. configuration. Make your Hevy API key available in the environment that starts
  103. Codex, then add the hosted server:
  104. ```bash
  105. export HEVY_API_KEY=your-hevy-api-key
  106. codex mcp add hevy \
  107. --url https://mcp.hevy-mcp.dev/mcp \
  108. --bearer-token-env-var HEVY_API_KEY
  109. ```
  110. Codex stores the environment variable name, not the key itself, in its MCP
  111. configuration. Restart Codex or begin a new session, then run `codex mcp list`
  112. to verify the server is configured.
  113. ##### Other Streamable HTTP clients
  114. Clients that accept a remote MCP URL and fixed headers commonly use this shape:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "hevy": {
  119. "url": "https://mcp.hevy-mcp.dev/mcp",
  120. "headers": {
  121. "Authorization": "Bearer your-hevy-api-key"
  122. }
  123. }
  124. }
  125. }
  126. ```
  127. Exact configuration keys vary by client. The hosted server requires support for
  128. Streamable HTTP and a fixed `Authorization` header.
  129. > [!IMPORTANT]
  130. > Treat the bearer value like a password. The Worker validates it with Hevy for
  131. > each request, does not store it, and forwards it to Hevy only as the required
  132. > `api-key` header.
  133. #### Run locally instead
  134. Choose local stdio if you prefer to run the server on your own machine or your
  135. client cannot attach a fixed authorization header to remote MCP requests.
  136. ##### Codex
  137. ```bash
  138. codex mcp add hevy \
  139. --env HEVY_API_KEY=your-hevy-api-key \
  140. -- npx -y hevy-mcp
  141. ```
  142. ##### Claude Desktop or Cursor
  143. Add this `mcpServers` entry to your client configuration:
  144. ```json
  145. {
  146. "mcpServers": {
  147. "hevy": {
  148. "command": "npx",
  149. "args": ["-y", "hevy-mcp"],
  150. "env": {
  151. "HEVY_API_KEY": "your-hevy-api-key"
  152. }
  153. }
  154. }
  155. }
  156. ```
  157. ##### Google Antigravity
  158. There are two ways to configure the Hevy MCP server for Google Antigravity (`agy`):
  159. ###### Option A: Automatic Plugin Installation (Recommended)
  160. This utilizes the built-in plugin system:
  161. The plugin reads the repository-root `mcp_config.json` to start the local
  162. stdio server. That configuration intentionally contains no API key; the server
  163. inherits `HEVY_API_KEY` from the host environment as described below. This is
  164. separate from the manual, user-global configuration described below and from
  165. the repository's `.mcp.json`, which configures hosted HTTP/OAuth.
  166. 1. Install the plugin:
  167. ```bash
  168. agy plugin install https://github.com/chrisdoc/hevy-mcp
  169. ```
  170. 2. Provide the `HEVY_API_KEY` in your host shell environment so the CLI child process can inherit it:
  171. - **Persistent:** Save the environment variable `HEVY_API_KEY` in your system/shell configurations:
  172. - **macOS / Linux:** Add it to your shell profile configurations (e.g., `~/.zshrc` or `~/.bashrc`):
  173. ```bash
  174. export HEVY_API_KEY="your-actual-api-key"
  175. ```
  176. - **Windows:** Add it to your User or System Environment Variables. In PowerShell, you can run:
  177. ```powershell
  178. [Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")
  179. ```
  180. - **Temporary (Session-only):** If you do not want to persist the key, export it in your active terminal session before running `agy`:
  181. ```bash
  182. export HEVY_API_KEY="your-actual-api-key"
  183. ```
  184. ###### Option B: Manual Configuration (No Plugin)
  185. If you prefer configuring it statically via the global configuration file:
  186. 1. Open your global MCP configuration file:
  187. - **Location:** `~/.gemini/config/mcp_config.json`
  188. 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:
  189. ```json
  190. {
  191. "mcpServers": {
  192. "hevy": {
  193. "command": "npx",
  194. "args": ["-y", "hevy-mcp"],
  195. "env": {
  196. "HEVY_API_KEY": "your-actual-api-key"
  197. }
  198. }
  199. }
  200. }
  201. ```
  202. Common local configuration locations:
  203. - **Claude Desktop on macOS:**
  204. `~/Library/Application Support/Claude/claude_desktop_config.json`
  205. - **Claude Desktop on Windows:**
  206. `%APPDATA%\Claude\claude_desktop_config.json`
  207. - **Cursor:** `~/.cursor/mcp.json`
  208. Restart or reconnect the client after saving the file.
  209. ##### Any stdio MCP client
  210. Configure your client to launch this command with `HEVY_API_KEY` in the child
  211. process environment:
  212. ```bash
  213. npx -y hevy-mcp
  214. ```
  215. `npx` requires Node.js 20 or newer. Restart or reconnect your client after
  216. saving its configuration.
  217. <details>
  218. <summary><strong>Use bunx instead</strong></summary>
  219. Requires [Bun](https://bun.sh/):
  220. ```json
  221. {
  222. "mcpServers": {
  223. "hevy": {
  224. "command": "bunx",
  225. "args": ["hevy-mcp@latest"],
  226. "env": {
  227. "HEVY_API_KEY": "your-hevy-api-key"
  228. }
  229. }
  230. }
  231. }
  232. ```
  233. </details>
  234. <details>
  235. <summary><strong>Use Docker instead</strong></summary>
  236. Official images support `linux/amd64` and `linux/arm64`. Keep stdin open with
  237. `-i` because the container runs the stdio MCP server:
  238. ```bash
  239. export HEVY_API_KEY=your-hevy-api-key
  240. docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest
  241. ```
  242. For an MCP client, store the key in a protected environment file and configure
  243. the client to launch Docker:
  244. ```json
  245. {
  246. "mcpServers": {
  247. "hevy": {
  248. "command": "docker",
  249. "args": [
  250. "run",
  251. "-i",
  252. "--rm",
  253. "--env-file",
  254. "/absolute/path/to/hevy-mcp.env",
  255. "ghcr.io/chrisdoc/hevy-mcp:latest"
  256. ]
  257. }
  258. }
  259. }
  260. ```
  261. Pin an exact image tag such as `ghcr.io/chrisdoc/hevy-mcp:X.Y.Z` when you need
  262. reproducible upgrades.
  263. </details>
  264. You can also add the npm server to supported clients with
  265. [`add-mcp`](https://github.com/neon-solutions/add-mcp):
  266. ```bash
  267. npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"
  268. ```
  269. ### 3. Ask your first question
  270. Try one of these after restarting or reconnecting your MCP client:
  271. - “Give me a training summary for the last four weeks.”
  272. - “What routines do I have saved on Hevy?”
  273. - “Show my three most recent workouts.”
  274. - “Find exercise templates containing squat.”
  275. - “Which Hevy account is connected?”
  276. Your assistant should ask for approval before mutation tools when the client
  277. supports tool confirmations.
  278. ## How it works
  279. ```text
  280. Hosted: Your AI assistant → Streamable HTTP → Cloudflare Worker → Hevy API
  281. Local: Your AI assistant → MCP over stdio → local hevy-mcp → Hevy API
  282. ```
  283. The hosted endpoint creates a fresh MCP server and Hevy client for each request.
  284. Direct bearer authentication uses the supplied Hevy key and caches successful
  285. validation for 15 minutes without persisting the raw key. OAuth instead stores
  286. the key encrypted in a grant. Neither path creates a shared MCP user session.
  287. The local server follows the same tool contract but receives the Hevy key
  288. through its process environment.
  289. In either mode, read tools retrieve data; mutation tools create or replace data
  290. only when your assistant calls them.
  291. ## Guided prompts
  292. These server-provided MCP prompts coordinate common multi-step workflows:
  293. | Prompt | Arguments | Workflow |
  294. | ----------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
  295. | `analyze-workout-progress` | Optional `weeks` from 1-12; default `4` | Calls `get-training-summary`, then analyzes workout activity and body-measurement trends from the returned evidence. |
  296. | `create-workout-from-routine` | Required `routine_id` and UTC `start_time` | Loads a routine, collects actual completed-set data and an end time, then creates a workout without inventing results. |
  297. ## Tools
  298. `hevy-mcp` registers 23 tools. Read-only tools are safe for exploration; create
  299. and update tools are exposed with MCP mutation annotations so compatible clients
  300. can request confirmation.
  301. | Category | Tool | Description |
  302. | ----------------- | ---------------------- | ------------------------------------------------------------------------------------- |
  303. | Training analysis | `get-training-summary` | Summarize 1-12 weeks of workout activity and body-measurement trends in one call. |
  304. | Workouts | `get-workouts` | List workouts in Hevy API order, not by start time, with exercise and timing details. |
  305. | Workouts | `get-workout` | Get complete details for one workout by ID. |
  306. | Workouts | `get-workout-events` | List workout update and delete events since a timestamp. |
  307. | Workouts | `create-workout` | Create a completed workout in Hevy. |
  308. | Workouts | `update-workout` | Patch workout metadata by ID; `is_private` is required, while other omitted fields and all exercises remain unchanged. |
  309. | Workouts | `replace-workout-exercises` | Replace all exercises and sets; `is_private` is required and updated, while other workout metadata remains unchanged. |
  310. | Routines | `search-routines` | Search routine titles and return compact metadata for discovery. |
  311. | Routines | `get-routines` | List custom and default workout routines. |
  312. | Routines | `get-routine` | Get one routine and its exercise configuration by ID. |
  313. | Routines | `create-routine` | Create a reusable workout routine. |
  314. | Routines | `update-routine` | Replace an existing routine's content. |
  315. | Routine folders | `get-routine-folder` | Get one routine folder's metadata by ID. |
  316. | Routine folders | `create-routine-folder` | Create a routine folder. |
  317. | Exercise templates | `get-exercise-template` | Get complete metadata for one exercise template by ID. |
  318. | Exercise templates | `search-exercise-templates` | Search the full exercise catalog by title substring. |
  319. | Exercise templates | `create-exercise-template` | Create a custom exercise template. |
  320. | Exercise history | `get-exercise-history` | Get past performed sets for one exercise template. |
  321. | Body measurements | `get-body-measurements` | List dated body measurements. |
  322. | Body measurements | `get-body-measurement` | Get the body measurement entry for one date. |
  323. | Body measurements | `create-body-measurement` | Create a dated body measurement. |
  324. | Body measurements | `update-body-measurement` | Update the body measurement for an existing date. |
  325. | Diagnostics | `feedback` | Report a concise, privacy-safe description of an issue or unexpected behavior. |
  326. `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:
  327. ```json
  328. {
  329. "routine": {
  330. "title": "Full Body A",
  331. "folder_id": 123,
  332. "notes": "First four exercises are the minimum viable workout",
  333. "exercises": [
  334. {
  335. "exercise_template_id": "30E293E3",
  336. "superset_id": null,
  337. "rest_seconds": 120,
  338. "notes": "Controlled active ROM",
  339. "sets": [
  340. {
  341. "type": "normal",
  342. "rep_range": {
  343. "start": 6,
  344. "end": 10
  345. }
  346. }
  347. ]
  348. }
  349. ]
  350. }
  351. }
  352. ```
  353. The Hevy API currently exposes no delete endpoints for workouts, routines,
  354. routine folders, exercise templates, or body measurements, so there are no
  355. corresponding delete tools.
  356. ### Resources
  357. | Name | URI | Description |
  358. | -------------------- | --------------------------- | -------------------------------------------- |
  359. | `user-profile` | `hevy://user` | Authenticated Hevy user profile. |
  360. | `workout-count` | `hevy://workout-count` | Total number of workouts in the account. |
  361. | `exercise-templates` | `hevy://exercise-templates` | Full formatted exercise template catalog. |
  362. | `routine-folders` | `hevy://routine-folders` | Full formatted list of Hevy routine folders. |
  363. ## Hosted Cloudflare endpoint
  364. The production MCP server is live at:
  365. ```text
  366. https://mcp.hevy-mcp.dev/mcp
  367. ```
  368. It is the quickest way to use `hevy-mcp`: there is nothing to install or keep
  369. running locally, and it exposes the same 23 tools as the npm package and Docker
  370. image.
  371. The Cloudflare Worker uses stateless **Streamable HTTP** at `POST /mcp`.
  372. Clients must send their Hevy API key as a fixed authorization header:
  373. ```json
  374. {
  375. "mcpServers": {
  376. "hevy": {
  377. "url": "https://mcp.hevy-mcp.dev/mcp",
  378. "headers": {
  379. "Authorization": "Bearer your-hevy-api-key"
  380. }
  381. }
  382. }
  383. }
  384. ```
  385. In this configuration the bearer value is your Hevy API key, not an OAuth
  386. token. The Worker caches successful validation for 15 minutes under a hashed
  387. key, does not persist the raw key on this direct path, and forwards it upstream
  388. only as Hevy's required `api-key` header.
  389. ### OAuth for Claude.ai and other remote MCP clients
  390. The hosted production Worker is deployed with an `OAUTH_KV` namespace binding,
  391. so it exposes a full OAuth 2.1 layer for clients that cannot send a fixed
  392. header, such as Claude.ai custom connectors. Self-hosted Workers can opt in by
  393. following the `OAUTH_KV` setup in [CONTRIBUTING.md](./CONTRIBUTING.md):
  394. - RFC 8414 / RFC 9728 discovery metadata under `/.well-known/`
  395. - Client ID Metadata Documents (CIMD), with dynamic client registration
  396. (`/register`) as a fallback, and PKCE token exchange (`/token`)
  397. - An `/authorize` page where you paste your Hevy API key once; the key is
  398. validated with Hevy and stored encrypted inside the OAuth grant
  399. Add the Worker URL ending in `/mcp` as a Claude.ai custom connector and
  400. complete the authorization flow in the browser. Direct
  401. `Authorization: Bearer <hevy-api-key>` requests keep working unchanged — the
  402. OAuth layer is purely additive. Revoking or rotating your Hevy key prevents
  403. subsequent Hevy API access with that key; it does not itself delete stored
  404. grants or immediately clear cached validation.
  405. OAuth access tokens last seven days and refresh tokens last 30 days. This
  406. reduces KV writes from frequent hourly refreshes while preserving automatic
  407. refresh for supported clients.
  408. The endpoint does not expose legacy SSE or a `GET` event stream. Without the
  409. opt-in OAuth layer, clients that require OAuth discovery, dynamic
  410. registration, CIMD, or token refresh are not compatible unless they can send
  411. the fixed custom header above.
  412. ### Self-host the Worker
  413. A clean clone can deploy the portable TypeScript Cloudflare configuration with
  414. `pnpm --dir packages/worker exec cf deploy` and receive a `workers.dev` URL. OAuth
  415. requires your own `OAUTH_KV` namespace; custom domains, routes, and
  416. observability destinations are optional account-owned settings. See
  417. [CONTRIBUTING.md](./CONTRIBUTING.md#cloudflare-worker-development) for setup and
  418. for the distinction between self-hosting and the maintainer-only named
  419. environments.
  420. See [CONTRIBUTING.md](./CONTRIBUTING.md) to deploy the Cloudflare Worker for
  421. self-hosted Streamable HTTP.
  422. ## Advanced configuration
  423. | Setting | Default | Scope | Notes |
  424. | -------------------------------- | ------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
  425. | `HEVY_API_KEY` | None; required | Local stdio or HTTP | Hevy API key from the Hevy app. Never pass it in a URL. |
  426. | `HEVY_MCP_API_TIMEOUT` | `60000` ms | Local stdio | Positive Hevy API timeout in milliseconds. Invalid values fall back to 60 seconds. |
  427. | `HEVY_MCP_DEBUG` | Disabled | Local Node | Set to exactly `1` for privacy-bounded diagnostics on stderr. Stdout remains reserved for MCP JSON-RPC. |
  428. | `HEVY_MCP_HTTP_BEARER_TOKEN` | None | Non-loopback HTTP | Required when `--host` is not loopback; use a separate token, never the Hevy API key. |
  429. | `HEVY_MCP_HTTP_MAX_SESSIONS` | `100` | Local HTTP | Maximum established sessions, including sessions currently initializing; excess requests receive `429`. |
  430. | `HEVY_MCP_HTTP_MAX_INITIALIZING` | `10` | Local HTTP | Maximum concurrent session initializations; excess requests receive `503` and are not queued. |
  431. | `HEVY_MCP_HTTP_IDLE_TIMEOUT_MS` | `1800000` ms | Local HTTP | Idle sessions are evicted after 30 minutes; each session request resets the timer. |
  432. | `HEVY_MCP_HTTP_BODY_TIMEOUT_MS` | `30000` ms | Local HTTP | Stalled request bodies receive `408`; values are bounded to five minutes. |
  433. | `HEVY_MCP_TELEMETRY` | Built: on; source: off | Local Node | Set `0` to disable telemetry or `1` to opt in for source runs. Imports remain side-effect-free. |
  434. | `HEVY_MCP_TELEMETRY_DIAGNOSTICS` | Enabled | Local Node | Set to exactly `0` to keep structural telemetry while suppressing exception messages and stacks. |
  435. | `XDG_CACHE_HOME` | `~/.cache` | Local stdio | Changes the root for the npm update-check cache at `hevy-mcp/update-check.json`. |
  436. | `SENTRY_DSN` | Packaged Sentry SaaS project DSN | Optional local Node telemetry | Sentry project DSN override. An empty value disables Sentry export. The Worker does not import Node telemetry. |
  437. | `SENTRY_RELEASE` | `hevy-mcp@<installed-version>` | Optional local Node telemetry | Overrides the release label attached to local Sentry error events. |
  438. | `SENTRY_ENVIRONMENT` | Built: `production`; source: `development` | Optional local Node telemetry | Overrides the environment label for enabled Sentry error events. |
  439. | `-h`, `--help` | N/A | Local stdio CLI | Print supported options and exit. |
  440. | `-v`, `--version` | N/A | Local stdio CLI | Print the installed version and exit. |
  441. The local Node executable uses stdio by default. Opt into local Streamable
  442. HTTP with:
  443. ```bash
  444. HEVY_API_KEY=your-hevy-api-key npx hevy-mcp --transport http --host 127.0.0.1 --port 3000
  445. ```
  446. The local MCP endpoint is `http://127.0.0.1:3000/mcp`; non-loopback binds
  447. require the separate `HEVY_MCP_HTTP_BEARER_TOKEN` environment variable. A
  448. Docker deployment must publish the port explicitly:
  449. ```bash
  450. docker run --rm -p 3000:3000 -e HEVY_API_KEY -e HEVY_MCP_HTTP_BEARER_TOKEN \\
  451. ghcr.io/chrisdoc/hevy-mcp:latest --transport http --host 0.0.0.0 --port 3000
  452. ```
  453. This Node HTTP mode is distinct from the stateless Cloudflare Worker HTTP
  454. endpoint described above: the Node server owns stateful client sessions, while
  455. the Worker is designed for hosted deployment and does not import Node code.
  456. ### Cache behavior
  457. `search-exercise-templates` and `hevy://exercise-templates` share a
  458. server-scoped in-memory catalog cache:
  459. - Entries live for five minutes, and the cache holds at most one catalog.
  460. - Concurrent catalog requests share an in-flight fetch when possible.
  461. - `search-exercise-templates` accepts `refresh: true` to invalidate the cache.
  462. - Each hosted Worker request gets a fresh catalog cache, preventing cross-key sharing.
  463. - Each local HTTP session owns its own MCP server and catalog cache; caches are
  464. not shared across sessions.
  465. ### Local Node telemetry and privacy
  466. Published Node builds enable project telemetry by default. Unbuilt source runs
  467. (such as development and probe scripts) disable it unless
  468. `HEVY_MCP_TELEMETRY=1` is set explicitly. This is local Node behavior only; the
  469. Cloudflare Worker does not import Node telemetry. Set `HEVY_MCP_TELEMETRY=0`
  470. before launching Node to disable all project telemetry in either mode. In
  471. published builds, every value except the literal `0` retains the enabled default.
  472. The scoped Node lifecycle Layer acquires telemetry; importing the package remains
  473. side-effect-free. Enabled source runs, and any build without an injected
  474. version (release `hevy-mcp@dev`), use the Sentry environment `development`;
  475. versioned published builds use `production`. Set `SENTRY_ENVIRONMENT` to
  476. override this label, for example to `qa` or `staging`. The master setting takes precedence over
  477. `SENTRY_DSN` and packaged or
  478. runtime `OTEL_COLLECTOR_TOKEN` credentials, so the disabled path creates no
  479. telemetry exporters or periodic metric readers and makes no telemetry network
  480. requests. `SENTRY_DSN` remains a Sentry-only setting; when telemetry is enabled,
  481. an empty value disables only Sentry export.
  482. When enabled, actionable errors are sent to the Sentry project configured by
  483. `SENTRY_DSN`; Sentry performance tracing is disabled. Exception messages and
  484. stacks are bounded and scrubbed before export. Set
  485. `HEVY_MCP_TELEMETRY_DIAGNOSTICS=0` to keep structural traces and metrics while
  486. suppressing those details. Traces and metrics continue to be sent to the
  487. collector at
  488. <https://otel.chrisdoc.dev/v1/traces> and
  489. <https://otel.chrisdoc.dev/v1/metrics>. The project uses its own OpenTelemetry
  490. Collector; downstream destinations are configured in that infrastructure.
  491. Metrics export every 30 seconds. See [observability documentation](./docs/observability.md)
  492. for Cloudflare OTLP export and domain tracing.
  493. The raw API key is never exported. Ordinary tool telemetry can include a short,
  494. deterministic HMAC pseudonym derived from the key for correlation; `feedback`
  495. uses a separate unobserved path. A per-failure diagnostic ID and OTel trace ID
  496. may be attached to actionable errors. See
  497. [telemetry data dictionary](./docs/telemetry-data-dictionary.md) for the bounded
  498. telemetry fields and privacy contract.
  499. Exception messages and stacks are treated as diagnostic details: they are
  500. length-limited, scrubbed for credentials, URLs, and local home paths, and
  501. removed entirely when `HEVY_MCP_TELEMETRY_DIAGNOSTICS=0`. Prompts, tool
  502. arguments, tool results, request bodies, API keys, raw identifiers/queries,
  503. exact dates, workout/routine/folder/template/body-measurement content,
  504. names/titles/descriptions/notes, measurement values, arbitrary client
  505. metadata, and unnormalized endpoint paths remain prohibited.
  506. ## Security and mutations
  507. - Keep `HEVY_API_KEY` out of source control, URLs, logs, and screenshots.
  508. - Local clients provide the key through the child process environment.
  509. - Direct hosted clients send the Hevy key only in the `Authorization: Bearer`
  510. header; successful validation is cached, but the raw key is not persisted.
  511. OAuth grants store the key encrypted. Both paths send it to Hevy only as the
  512. `api-key` header.
  513. - Browser MCP requests must be same-origin or match an exact allowlisted
  514. origin. The default allowlist includes Claude.ai, ChatGPT, VS Code for the
  515. Web, and github.dev; self-hosted deployments can override it with
  516. `MCP_ALLOWED_ORIGINS`. See [deployment modes](./docs/deployment-modes.md#origins-and-self-hosting)
  517. for the OAuth authorization-form exception.
  518. - Local development can copy `.dev.vars.example` to `.dev.vars` to disable
  519. Origin validation for MCP Inspector. PR preview Workers use the same
  520. development-only setting because their browser origins are dynamic. Never
  521. set `MCP_DISABLE_ORIGIN_CHECK=true` on a production Worker.
  522. - Create operations can produce duplicates when retried. Routine updates
  523. replace content; workout metadata updates preserve omitted fields and
  524. exercises, while `replace-workout-exercises` replaces all exercises and sets.
  525. Review tool inputs and use client confirmations.
  526. ## Troubleshooting
  527. - **The server does not appear:** restart or reconnect your MCP client after
  528. changing its configuration.
  529. - **`npx` fails:** confirm that Node.js 20 or newer is installed, then run
  530. `npx -y hevy-mcp --version` in a terminal.
  531. - **Codex cannot see the server:** run `codex mcp list`, then start a new Codex
  532. session after confirming the `hevy` entry exists.
  533. - **Hevy API returns 401:** the key is invalid, expired, revoked, or
  534. misconfigured. Verify or create an active key at
  535. [Hevy's API settings](https://hevy.com/settings?developer), then restart the client.
  536. - **Hosted authentication fails:** confirm the key belongs to a Hevy PRO
  537. account and is sent as `Authorization: Bearer <HEVY_API_KEY>`.
  538. - **Local authentication fails:** confirm the key is active and available to the
  539. MCP child process as `HEVY_API_KEY`.
  540. - **Need diagnostics:** set `HEVY_MCP_DEBUG=1`. Diagnostic output goes to stderr
  541. and does not interfere with MCP messages on stdout.
  542. If you find a bug or have a feature request, [open an issue](https://github.com/chrisdoc/hevy-mcp/issues).
  543. ## Contributing
  544. Contributions are welcome. Developer setup, testing lanes, generated-client
  545. workflows, Cloudflare Worker deployment, and pull request rules are documented
  546. in [CONTRIBUTING.md](./CONTRIBUTING.md).
  547. Use mise for the pinned Node.js and pnpm versions, then run the deterministic
  548. unit lane. It does not need a live Hevy API key:
  549. ```bash
  550. MISE_AUTO_INSTALL=false mise install
  551. MISE_AUTO_INSTALL=false mise exec -- pnpm install
  552. MISE_AUTO_INSTALL=false mise exec -- pnpm run test:unit
  553. ```
  554. ## License and acknowledgements
  555. - **License:** [MIT](./LICENSE)
  556. - **Credits:** [Model Context Protocol](https://github.com/modelcontextprotocol)
  557. and [Hevy Fitness](https://www.hevyapp.com/)

Version history

  • v1.0.010/21/2026

  • v6.2.110/18/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.