Hevy (unofficial)

io.github.almostjackedPublished by GitHub account almostjackedv0.1.0Updated Oct 24, 2026

Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.

VerifiedStreamable HTTPWeb executableLocation & LifestyleData & Analytics

Overview

AI-generated overview

Unofficial Hevy MCP server that lets an assistant create workout routines in your Hevy account and analyze your logged training.

What you can do
  • Search the Hevy exercise library by name and list or create routine folders
  • List existing routines, read one routine in full, create routines and replace existing ones
  • Read recent logged workouts, single workouts set by set, and total workout count
  • Review per-exercise history with past sets and estimated 1RM, plus a weekly training summary of sessions, volume, sets per muscle group and top-lift trend
When to use it
Useful if you already log training in Hevy and want an assistant to draft or adjust routines directly in your account, or to summarize volume, muscle-group balance and strength trends from your history.
Requirements
A Hevy PRO API key from the Hevy developer settings. Either the hosted remote endpoint with OAuth sign-in, the one-click desktop bundle, or a local npm package run with npx and the HEVY_API_KEY environment variable. Self-hosting needs a Cloudflare Workers account and an AUTH_TOKEN secret for bearer authentication.
Before you install
Creating and updating routines writes to your Hevy account, and update_routine replaces a routine's exercises with exactly what is sent, so existing exercises can be lost if not included. The API key is a credential; the hosted instance receives it and stores it in your OAuth grant, while local and desktop versions run on your machine. Training data is sent to Hevy's API.

Installation

In SourceWeft

  1. Open Hevy (unofficial) in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.almostjacked%2Fhevy-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "hevy-unofficial": {
      "type": "http",
      "url": "https://hevy-coach.ajwallacemusic.workers.dev/mcp"
    }
  }
}

README

hevy-mcp

[CI] [npm] [MCP Registry] [Install in Cursor] [Install in VS Code]

Unofficial MCP server for Hevy. Design training programs in chat; your AI creates the routines directly in your Hevy account and analyzes your logged training. Requires a Hevy PRO API key (hevy.com/settings?developer).

Use it

Hosted (easiest — claude.ai web, mobile, desktop)

Add a custom connector in claude.ai → Settings → Connectors:

https://hevy-coach.ajwallacemusic.workers.dev/mcp

You'll be prompted for your Hevy API key; it's stored encrypted in your own OAuth grant and sent only to api.hevyapp.com.

Claude Desktop one-click

Download hevy-mcp.mcpb, double-click, paste your key when prompted.

Local (Claude Code / Cursor / any stdio client)

claude mcp add hevy -e HEVY_API_KEY=<key> -- npx -y @almostjacked/hevy-mcp

Self-host (free, your own infra)

The published package ships the worker — no clone needed:

bash
mkdir hevy-worker && cd hevy-worker && npm init -ynpm install @almostjacked/hevy-mcp wranglercat > wrangler.jsonc <<'EOF'{  "name": "hevy-mcp",  "main": "node_modules/@almostjacked/hevy-mcp/dist/worker.js",  "compatibility_date": "2026-07-01",  "compatibility_flags": ["nodejs_compat"]}EOFnpx wrangler deploynpx wrangler secret put AUTH_TOKEN     # any long random string — becomes your Bearer tokennpx wrangler secret put HEVY_API_KEY   # from hevy.com/settings?developer

Add your worker URL (https://hevy-mcp.<your-subdomain>.workers.dev/mcp) to clients that support custom headers — e.g. Claude Code: claude mcp add --transport http hevy-selfhost <url> --header "Authorization: Bearer <token>". claude.ai custom connectors don't support custom auth headers; for claude.ai use the hosted instance above, or front your worker with Cloudflare Access.

Tools

ToolDescription
search_exercisesSearch the user's Hevy exercise library by name (fuzzy). Returns template id, exact title, type, muscle group and equipment.
list_routine_foldersList the user's routine folders (id + title). Check this before creating a folder — reuse an existing one when the name matches.
create_routine_folderCreate a routine folder, or return the existing folder if one with this exact title already exists (never duplicates).
list_routinesList the user's existing routines (id, title, folder_id, exercise_count). Use to avoid creating duplicates.
create_routinecreate a routine (lb-first: weight_lb snaps to 2.5/5 lb increments; RPE folded into notes; supersets; duration/distance targets supported)
get_workoutsGet the user's most recent logged workouts, newest first, as compact summaries: title, date, duration, and per-exercise set count + top set. Use get_workout for full set-by-set detail of one workout.
get_workoutGet one logged workout with every set (weights in kg). Use the id from get_workouts.
get_workout_countTotal number of workouts the user has ever logged in Hevy.
get_exercise_historypast sets + estimated 1RM in lb for one exercise (full history, optional date range)
get_routineGet one routine in full (all exercises and sets). Always call this before update_routine so you can send back the complete routine.
update_routineReplace an existing routine. WARNING: this overwrites the routine — Hevy replaces its exercises with exactly what you send, so first call get_routine and include every exercise you want to keep. Folder cannot be changed here; duration/distance/custom-metric set targets round-trip safely.
get_training_summaryweekly sessions/volume (lb), sets per muscle group, top-lift 1RM trend

Privacy Policy

Your Hevy API key and training data pass through only to api.hevyapp.com. The stdio/.mcpb versions run entirely on your machine. The hosted instance stores nothing but your encrypted OAuth grant; disconnecting revokes it. Nothing is logged or shared with third parties.

Source: README.md at commit 0fd889e

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts