Hevy MCP

Community

Manage your Hevy workout data from AI assistants via MCP.

How to install ↓ Compare GitHub source repository ↗

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

77FMRS · B

Hevy MCP Server is an unofficial MCP server for the Hevy fitness app. It provides 26 tools for managing workouts, routines, exercise templates, and body measurements, requiring a Hevy API key (requires Hevy PRO). It supports various MCP clients, runs locally via npm or Docker, and can be hosted remotely via a Cloudflare Worker HTTP endpoint.

Strongest · Documentation 18/20 Weakest · Reliability 12/20

Reliability

12/20

Security and permissions

16/20

Maintenance

16/20

Documentation

18/20

Setup experience

15/20

Why each score

Reliability 12/20: Evidence: The repo contains server.json manifest pointing to npm package 'hevy-mcp' with stdio transport. README lists 26 tools and resources. CI workflow (build-and-test.yml) and Codecov badge suggest tests and coverage, but static review did not execute code, so actual behavior and error handling are unverified. Deductions: No direct evidence of committed unit/integration tests, edge cases or failure modes unproven. Thus cap at 12.
Security and permissions 16/20: Evidence: Server requires HEVY_API_KEY marked required and secret. README emphasizes not putting key in source control, URLs, logs, and provides security guidelines. Deployed Cloudflare Worker uses bearer token, does not store key, and supports OAuth with key stored encrypted. Mutating tools have MCP mutation annotations allowing client confirmation. No red-line issues seen. Deductions: No code-level evidence that all tools correctly implement confirmation or input validation, but no red flags.
Maintenance 16/20: Evidence: MIT license, active GitHub repo (385 stars, 14 open issues, not archived). README shows ongoing development, multiple versions (5.1.0), and detailed CLI, Worker, Docker deployment. Contributing guide and CI present. Deductions: Cannot verify commit frequency or issue response from static review alone, but repo appears well-maintained.
Documentation 18/20: Evidence: Comprehensive README covering installation, authentication, configuration, tools, resources, troubleshooting, security, and privacy. Clear env var table, client config examples, hosted and local install docs, demo and examples. Deductions: Documentation is mostly from README, which is untrusted evidence, but static analysis shows it is detailed and structured. No deductions, but cap at 18 due to untrusted source.
Setup experience 15/20: Evidence: README offers multiple install methods: npm (npx), bunx, Docker, hosted Cloudflare endpoint. Step-by-step client configuration examples for Claude Desktop, Cursor, Codex, Google Antigravity. Env var HEVY_API_KEY clearly documented. Deductions: Cannot exceed 15 without verification of CI and tests; static review does not verify install steps actually work, but documentation provides clear guidance.

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 who want AI assistants to directly access their workout data
People who prefer using MCP clients like Claude, Cursor, Codex for fitness tracking
Anyone needing summaries and insights from their training data

Not for

Users without a Hevy PRO subscription (API key required)
Users who want to use the server without an API key
Those needing delete workflows (Hevy API does not expose delete endpoints)

Required permissions

Requires HEVY_API_KEY environment variable for Hevy API authentication
Can create, update, and replace workouts, routines, folders, templates, and body measurements via tools
Read operations can fetch workouts, routines, folders, templates, history, and user info

Risks and side effects

API key can be misused if leaked; do not expose in URLs, logs, or screenshots
Create operations may produce duplicates on retry; update operations replace existing records
The server sends data to the Hevy API and may send telemetry to external services unless disabled

Setup

Before you start

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

HEVY_API_KEY requiredsecret API key from the Hevy app for authentication; currently requires a Hevy PRO subscription.

HEVY_MCP_HTTP_BEARER_TOKEN optionalsecret Optional; access token required when binding local HTTP mode to non-loopback hosts; must not be the Hevy API key.

Other optional settings (7)

HEVY_MCP_API_TIMEOUT optional Optional; Hevy API timeout in milliseconds, defaults to 30000.

HEVY_MCP_DEBUG optional Optional; set to 1 for privacy-bounded diagnostics on stderr.

HEVY_MCP_TELEMETRY optional Optional; set to 0 before startup to disable all project telemetry.

XDG_CACHE_HOME optional Optional; changes the root for the npm update-check cache.

SENTRY_DSN optional Optional; Sentry-compatible error reporting destination override; empty value disables Sentry export.

SENTRY_RELEASE optional Optional; overrides the release label attached to local Sentry error events.

MCP_ALLOWED_ORIGINS optional Optional; overrides the browser origin allowlist on self-hosted deployments.

Obtain a Hevy API key from the Hevy app (requires Hevy PRO).
Configure your MCP client to use 'npx -y hevy-mcp' with the environment variable HEVY_API_KEY. Alternatively, use Docker: 'docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest'.
Add the provided JSON configuration to your client's mcpServers.
Restart or reconnect your MCP client.

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 connecting, ask “Which Hevy account is connected?” — get-user-info should return the account's ID, display name, and public profile URL, confirming the setup works.

Troubleshooting

Ensure Node.js 20 or newer is installed
Confirm HEVY_API_KEY is set correctly as an environment variable
Restart or reconnect your MCP client after configuration changes
Check that the API key is valid and belongs to a Hevy PRO account

Things to try

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

Give me a training summary for the last four weeks.
Analyze my training over the last six weeks: workouts per week, most frequently trained exercises, and any consistency gaps.
Find my push-day routine and show its exercises and sets.
Search exercise templates containing squat.

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: summarize 1-12 weeks of workouts and body measurements.

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, folders, custom exercises, and body measurements.

Search without huge responses: discover routines and exercise templates with compact, AI-friendly results.

Supported clients

Claude Desktop

Cursor

Codex

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 enables AI assistants to read, analyze, create, and update your Hevy workouts, routines, exercise templates, and body measurements through authenticated Hevy API requests. The server runs locally via npm with stdio transport and requires a Hevy API key (requires Hevy PRO). It registers 26 tools, 4 resources, and 2 guided prompts.

Similar servers

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.

★ 654 · Tools 11 Compare with this →

Compartment 75 · B

Encrypted, fully offline long-term memory for AI agents

★ 579 · Tools 14 Compare with this →

Exa MCP Server 73 · B

Exa's official MCP server for web search and crawling built for AI applications

★ 5.1k · Tools 4 Compare with this →

Compare with other MCP servers

More servers from this repository

Source revision c7ad9cabda93 Data synced 2026-10-12 Read the FMRS scoring method