Hevy MCP Server

Community

Manage workouts, routines, and exercise data through the Hevy API

How to install ↓ Compare GitHub source repository ↗

Category: Other #30 of 230
Stars: ★ 509 Very popular
Transport: stdio (local process) · Streamable HTTP
Runtime: Node.js 20+ · Docker · Bun · Hosted (no local runtime)
Credentials: API key / credential required
License: MIT
Last commit: 1 day ago
Tools: 26

66FMRS · C

Hevy MCP Server is a feature-rich MCP server providing 26 tools to manage Hevy data, supporting both local stdio and hosted Streamable HTTP modes. It is ideal for advanced users who want AI-assisted training analysis, but requires a Hevy PRO subscription and is not an official product. Security considerations include API key protection and telemetry privacy.

Strongest · Documentation 17/20 Weakest · Reliability 9/20

Reliability

9/20

Security and permissions

14/20

Maintenance

12/20

Documentation

17/20

Setup experience

14/20

Why each score

Reliability 9/20: The manifest is internally consistent (npm hevy-mcp 5.1.0, stdio transport, required secret HEVY_API_KEY), the README's claim of 26 tools matches the 26 rows actually listed, the read/update tool split is sensible, and the absence of delete tools is correctly explained by the Hevy API having no delete endpoints. However, this is a static review: the supplied material contains no real CI workflow files or committed test sources that would prove the server starts cleanly and completes the MCP init and tool-list handshake. The documented error handling (API timeout fallback, HEVY_MCP_DEBUG, SDK v1.29.0 default-arguments quirk) suggests care, but it is README claims rather than verifiable execution evidence; the calibration caps reliability accordingly, so I deducted for unverifiable evidence.
Security and permissions 14/20: For the scored Node stdio server, the API key is declared required and secret in the manifest; docs say it is passed via child-process environment locally, never placed in URLs/logs/screenshots, and create/update tools carry MCP mutation annotations so compatible clients can require confirmation. There are no delete/deploy/pay tools, hence no irreversible default actions. Telemetry is enabled by default but has an explicit opt-out and a detailed privacy allowlist that prohibits raw arguments, results, identifiers, and body content. Deductions: telemetry is on by default; the single API key grants full read/write access to the account with confirmation left to the client rather than enforced server-side; README security claims about origin allowlists, the Worker not storing keys, and OAuth encryption belong to the unscored sibling Cloudflare server and cannot be credited to the Node package, and encryption/validation behavior is not statically verifiable.
Maintenance 12/20: The repository is not archived, has an MIT license, has reached version 5.1.0, and the unusually detailed README referencing CONTRIBUTING.md and CI badges indicates ongoing development; however, CI/Codecov badges are untrusted claims. Deductions: the supplied material contains no commit history, release dates, dependency-update evidence, or issue-response timeliness data to confirm sustained maintenance, and 14 open issues show a visible backlog. Overall this is 'active but governance and versioning evidence largely unverifiable from the provided source.'
Documentation 17/20: Documentation is layered and deep: quick start, hosted vs local modes, client-specific config examples for Codex/Claude Desktop/Cursor/Antigravity/bunx/Docker/add-mcp, a complete 26-tool and resource table, an environment-variable reference with defaults and notes, cache behavior, telemetry and privacy disclosure, security and mutation semantics, troubleshooting, and even an MCP SDK v1.29.0 compatibility note. Limitations (Hevy PRO requirement, no delete endpoints, optional OAuth) are disclosed. Deductions: there is no full per-tool argument/input-schema reference, no explicit API rate-limit or cost information, no visible changelog, and CONTRIBUTING.md and the CLI README are referenced but not supplied.
Setup experience 14/20: Setup is genuinely few-step: obtain an API key, then either configure the hosted URL with an Authorization header (zero install) or run `npx -y hevy-mcp` with HEVY_API_KEY locally; the Node 20+ requirement is stated and config examples for multiple mainstream clients plus setup troubleshooting are provided. Deductions: the static calibration caps setup at 15 because no verifiable CI workflows and committed tests are present in the supplied material; the Docker, Antigravity manual-config, and local HTTP-mode paths add manual steps, and the key must be carefully managed per client environment, so some fragility remains.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

Hevy PRO users
Fitness enthusiasts who want AI-assisted training analysis and planning
Developers who want to integrate Hevy data into MCP clients like Claude Desktop, Codex, Cursor

Not for

Users without Hevy PRO subscription
Users who need deletion capabilities (Hevy API does not expose delete endpoints)
Users looking for official support (this is community-maintained, not affiliated with Hevy)

Required permissions

Requires Hevy API key (`HEVY_API_KEY`)
Can read and write Hevy data (workouts, routines, exercise templates, body measurements, etc.)
Hosted endpoint validates the API key with Hevy on each request and forwards it as `api-key` header

Risks and side effects

API key leakage risk: never put key in source control, URLs, logs, or screenshots.
Mutation risk: create operations may produce duplicates on retry; update operations replace existing records.
Privacy: local package enables telemetry by default (can be disabled), sending errors and metrics to external services.
Dependency on third-party service: hosted endpoint relies on Cloudflare Worker, availability may vary.
Tool confirmation: mutation tools may require client confirmation, but support varies by client.

Setup

Before you start

Runtime：Node.js 20+ · Docker · Bun · Hosted (no local runtime)

HEVY_API_KEY requiredsecret API key from the Hevy app; requires a Hevy PRO subscription to generate.

HEVY_MCP_HTTP_BEARER_TOKEN optionalsecret Separate token required when binding local HTTP to a non-loopback host; never use the Hevy API key.

Other optional settings (8)

HEVY_MCP_API_TIMEOUT optional Hevy API timeout in milliseconds, default 30000, local stdio only.

HEVY_MCP_DEBUG optional Set to 1 for privacy-bounded diagnostics on stderr.

HEVY_MCP_TELEMETRY optional Set to exactly 0 before startup/import to fully disable local Node telemetry.

XDG_CACHE_HOME optional Changes the root for the npm update-check cache at hevy-mcp/update-check..

SENTRY_DSN optional Sentry-compatible override for the error-reporting destination; an empty value disables Sentry export.

SENTRY_RELEASE optional Overrides the release label attached to local Sentry error events.

MCP_ALLOWED_ORIGINS optional Self-hosted deployments can override the default browser origin allowlist.

MCP_DISABLE_ORIGIN_CHECK optional Development-only switch to disable origin validation; never set on a production Worker.

Create an API key in Hevy (requires Hevy PRO).
For local install, add npx -y hevy-mcp to your MCP client config with environment variable HEVY_API_KEY.
For hosted endpoint, use https://mcp.hevy-mcp.dev/mcp as Streamable HTTP URL with Authorization: Bearer <HEVY_API_KEY> header.
Restart or reconnect the client and ask your first question.

claude_desktop_config.json

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

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

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

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add hevy -e HEVY_API_KEY=your-hevy-api-key -- npx -y hevy-mcp

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After restarting the client, confirm the hevy server's 26 tools (such as get-user-info) appear in the tool list, then ask "Which Hevy account is connected?" — a response with your user ID and display name proves the connection works.

Troubleshooting

If server doesn't appear, restart or reconnect your MCP client after config changes.
If `npx` fails, ensure Node.js 20 or newer and run `npx -y hevy-mcp --version`.
If Codex can't see server, run `codex mcp list` and start a new session after confirming 'hevy' entry.
If hosted auth fails, confirm key is active, belongs to Hevy PRO account, and is sent as `Authorization: Bearer <HEVY_API_KEY>`.
For diagnostics, set `HEVY_MCP_DEBUG=1`; output goes to stderr and doesn't interfere with MCP.
If local auth fails, confirm key is active and available to child process as `HEVY_API_KEY`.

Things to try

Once connected, you can ask your AI assistant things like:

Analyze my training over the last six weeks. Show workouts per week, my most frequently trained exercises, and cite the workout evidence you used.
Give me a training summary for the last four weeks.
Find exercise templates containing squat.
Find my push-day routine and show its exercises and sets.

Tools 26

get-training-summary read-only

Summarize 1-12 weeks of workout activity and body-measurement trends in one call.

get-workouts read-only

List workouts from newest to oldest with exercise and timing details.

get-workout read-only

Get complete details for one workout by ID.

get-workout-count read-only

Return the account's total workout count.

get-workout-events read-only

List workout update and delete events since a timestamp.

create-workout writes

Create a completed workout in Hevy.

update-workout writes

Patch workout metadata by ID; omitted fields and all exercises remain unchanged.

replace-workout-exercises writes

Replace all exercises and sets while preserving workout metadata.

Show 18 more tools

search-routines read-only

Search routine titles and return compact metadata for discovery.

get-routines read-only

List custom and default workout routines.

get-routine read-only

Get one routine and its exercise configuration by ID.

create-routine writes

Create a reusable workout routine.

update-routine writes

Replace an existing routine's content.

get-routine-folders read-only

List default and custom routine folders.

get-routine-folder read-only

Get one routine folder's metadata by ID.

create-routine-folder writes

Create a routine folder.

get-exercise-templates read-only

List exercise templates with equipment and muscle metadata.

get-exercise-template read-only

Get complete metadata for one exercise template by ID.

search-exercise-templates read-only

Search the full exercise catalog by title substring.

create-exercise-template writes

Create a custom exercise template.

get-exercise-history read-only

Get past performed sets for one exercise template.

get-body-measurements read-only

List dated body measurements.

get-body-measurement read-only

Get the body measurement entry for one date.

create-body-measurement writes

Create a dated body measurement.

update-body-measurement writes

Update the body measurement for an existing date.

get-user-info read-only

Return the user's ID, display name, and public profile URL.

Use cases

Analyze training progress over recent weeks, frequency, exercise distribution, and body measurement trends.

Query recent workouts, frequently trained exercises, routine details, or exercise history in natural language.

Create or update workouts, routines, folders, custom exercises, and body measurements.

Search exercise templates and routines with compact, AI-friendly results.

Supported clients

Claude Desktop

Codex

Cursor

Antigravity

Listed from the project's documentation, not tested by this site.

Overview

Hevy MCP Server is an open-source Model Context Protocol (MCP) server for the Hevy fitness and workout tracking app. It allows AI assistants to read, analyze, create, and update your Hevy workouts, routines, exercise templates, and body measurements through authenticated Hevy API requests. It supports multi-step workflows, guided prompts, and a wide range of tools for training analysis, exercise search, and planning.

Similar servers

Hevy MCP 77 · B

Manage your Hevy workout data from AI assistants via MCP.

★ 509 · Tools 26 Compare with this →

Firecrawl MCP Server 75 · B

Firecrawl's official MCP server for web search, scraping, and structured extraction for AI agents

★ 7.6k · Tools 11 Compare with this →

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 653 · Tools 11 Compare with this →

Compartment 75 · B

Encrypted, fully offline long-term memory for AI agents

★ 579 · Tools 14 Compare with this →

Compare with other MCP servers

More servers from this repository

Source revision 1f9f9189883c Data synced 2026-10-11 Read the FMRS scoring method