Routine tools — manage Hevy workout routines and folders

Hevy MCP provides 5 routine tools for browsing, searching, and managing saved workout plans, plus 3 folder tools for organizing routines into named groups. Read-only tools are safe for exploration at any time; write tools create or replace data and are annotated as mutations so compatible MCP clients can request confirmation before executing.

search-routines

Find routine IDs by title substring with compact metadata

get-routines

Paginated list of routines with full exercise configuration

get-routine

Single routine with full exercise configuration by ID

create-routine

Create a new reusable workout plan

update-routine

Replace an existing routine’s content

Folder tools

Browse, fetch, and create routine folders

search-routines

Read-only. Discovers routines by title and returns compact metadata without full set payloads. Scans all routine pages (at pageSize 10 internally) and filters by title substring.

Kind: Read-only

Use search-routines first to find a routine ID or shortlist plans, then call get-routine for the full exercise configuration of a specific routine.

Input parameters

query

string

Optional case-insensitive substring to match against routine titles. Omit to return the first limit routines across all pages.

limit

integer

default:"20"

Maximum number of compact routines to return. Must be between 1 and 100.

Response fields

Each result in the returned array contains:

Field	Type	Description
`id`	string	Routine ID, usable directly in `get-routine`
`title`	string	Routine title
`folderId`	number \| null	Folder the routine belongs to, or `null`
`updatedAt`	string	ISO 8601 timestamp of last modification
`exerciseCount`	integer	Number of exercises in the routine
`setCount`	integer	Total number of sets across all exercises

Full set payloads (weights, reps, distances, etc.) are intentionally omitted from results. Call get-routine with the returned id to access the complete exercise configuration.

get-routines

Read-only. Lists custom and default workout routines with their full exercise configuration, paginated.

Kind: Read-only

Input parameters

page

integer

default:"1"

Page number to retrieve. Must be ≥ 1.

pageSize

integer

default:"5"

Number of routines per page. Must be between 1 and 10.

pageSize is capped at 10. Use search-routines when you need to scan across all routines for a specific title.

get-routine

Read-only. Retrieves one routine and its complete exercise configuration by ID.

Kind: Read-only

Input parameters

routineId

string

required

The ID of the routine to retrieve. Must be a non-empty string. Obtain this from get-routines, search-routines, or a prior create-routine response.

create-routine

Write (mutation). Creates a new workout routine in the Hevy account, including its exercise list and set configuration.

Kind: Write

This operation cannot be undone. Retrying on failure can create duplicate routines with identical titles. Verify the routine does not already exist with search-routines before calling this tool.Non-fixed rep ranges (where repRange.start ≠ repRange.end) may not display correctly in Hevy mobile and web apps, even though the data is stored.

Input parameters

title

string

required

Routine title. Must be at least 1 character.

notes

string

Optional free-text notes attached to the routine.

folderId

number | null

Optional ID of the routine folder to place this routine in. Use get-routine-folders to discover valid folder IDs.

exercises

array

required

Array of exercise objects. Each exercise requires the following fields:

Show Exercise object fields

exerciseTemplateId

string

required

Non-empty ID of the exercise template. Use search-exercise-templates to look up IDs by name.

supersetId

number | null

Numeric superset group identifier. Exercises sharing the same supersetId are grouped as a superset. Pass null for no superset.

restSeconds

integer

Rest period after this exercise in seconds. Must be ≥ 0.

notes

string

Optional per-exercise notes.

sets

array

required

Array of set objects for this exercise.

Show Set object fields

type

string

default:"normal"

Set type. One of warmup, normal, failure, or dropset.

weightKg

number

Load in kilograms. Pass null or omit for bodyweight or duration exercises.

reps

integer | null

Target rep count. Pass null for duration-based sets.

distanceMeters

integer

Distance in meters, for distance-based exercises.

durationSeconds

integer

Duration in seconds, for timed exercises.

customMetric

number

Custom numeric metric value when the exercise type uses a custom metric.

repRange

object

Optional target rep range object. When provided, overrides a fixed reps value in the Hevy UI.

Show repRange fields

start

integer | null

Lower bound of the rep range (e.g., 8 for “8–12 reps”).

end

integer | null

Upper bound of the rep range (e.g., 12 for “8–12 reps”).

Example

{
  "title": "Upper Body Push",
  "notes": "Monday session",
  "folderId": null,
  "exercises": [
    {
      "exerciseTemplateId": "A10D7A3C-B607-4B4B-B85D-5C9C86C71C63",
      "supersetId": null,
      "restSeconds": 120,
      "notes": "Focus on chest stretch",
      "sets": [
        { "type": "warmup", "weightKg": 40, "reps": 15 },
        { "type": "normal", "weightKg": 80, "repRange": { "start": 8, "end": 12 } },
        { "type": "normal", "weightKg": 80, "repRange": { "start": 8, "end": 12 } }
      ]
    }
  ]
}

update-routine

Write (mutation). Replaces an existing routine’s title, notes, and complete exercise list.

Kind: Write

The exercises array is a full replacement — exercises not included in the payload are permanently removed from the routine. Always pass the complete desired exercise list.Non-fixed rep ranges (where repRange.start ≠ repRange.end) may not display correctly in Hevy mobile and web apps.

Input parameters

routineId

string

required

ID of the routine to update. Must be a non-empty string. Obtain this from get-routines or search-routines.

title

string

required

Updated routine title. Must be at least 1 character.

notes

string

Optional free-text notes. Omit to clear existing notes.

exercises

array

required

Complete replacement list of exercise objects. Uses the same shape as create-routine exercises — see that section for the full field reference including sets, restSeconds, supersetId, and repRange.

Routine folder tools

Routine folders let you group related routines (e.g., “Strength Block”, “Cardio Week”). Use get-routine-folders to discover folder IDs before creating routines that reference a folderId.

get-routine-folders

Read-only. Lists all default and custom routine folders, paginated.

Kind: Read-only

Input parameters

page

integer

default:"1"

Page number to retrieve. Must be ≥ 1.

pageSize

integer

default:"5"

Number of folders per page. Must be between 1 and 10.

get-routine-folder

Read-only. Retrieves metadata for a single routine folder by ID.

Kind: Read-only

Input parameters

folderId

string

required

The ID of the folder to retrieve. Must be a non-empty string. Obtain this from get-routine-folders or a prior create-routine-folder response.

create-routine-folder

Write (mutation). Creates a new routine folder in the Hevy account.

Kind: Write

Retrying on failure, or reusing a folder name, can create duplicate folders. Check for an existing folder with get-routine-folders before creating a new one.

Input parameters

name

string

required

Name of the new folder. Must be at least 1 character.

Example

{
  "name": "Strength Block – Q1"
}

Recommended workflow

search-routines (query="push")       → find the routine ID
get-routine (routineId="abc123")     → inspect full exercise details
update-routine (routineId="abc123")  → make changes with the full exercises list

For creating a new routine inside a folder:

get-routine-folders                            → list folders
create-routine-folder (name="New Block")       → create if needed
search-exercise-templates (query="bench press") → resolve template IDs
create-routine (folderId=..., exercises=[...]) → create the routine

Overview

Workouts

Routines

Exercise Templates

Body Measurements & Account

Routine tools — manage Hevy workout routines and folders

search-routines

get-routines

get-routine

create-routine

update-routine

Folder tools

search-routines

Input parameters

Response fields

get-routines

Input parameters

get-routine

Input parameters

create-routine

Input parameters

Example

update-routine

Input parameters

Routine folder tools

get-routine-folders

Input parameters

get-routine-folder

Input parameters

create-routine-folder

Input parameters

Example

Recommended workflow

search-routines

get-routines

get-routine

create-routine

update-routine

Folder tools

​search-routines

​Input parameters

​Response fields

​get-routines

​Input parameters

​get-routine

​Input parameters

​create-routine

​Input parameters

​Example

​update-routine

​Input parameters

​Routine folder tools

​get-routine-folders

​Input parameters

​get-routine-folder

​Input parameters

​create-routine-folder

​Input parameters

​Example

​Recommended workflow

search-routines

Input parameters

Response fields

get-routines

Input parameters

get-routine

Input parameters

create-routine

Input parameters

Example

update-routine

Input parameters

Routine folder tools

get-routine-folders

Input parameters

get-routine-folder

Input parameters

create-routine-folder

Input parameters

Example

Recommended workflow