Exercise template tools — search and manage Hevy exercises

Hevy MCP provides 5 exercise template tools for browsing, searching, and creating exercises in your Hevy catalog, plus querying the historical performance of any individual movement. Read-only tools are safe for exploration at any time; create-exercise-template is a write tool that adds a custom exercise to your account.

search-exercise-templates

Find templates by name substring across the full catalog

get-exercise-templates

Paginated catalog browsing with muscle and equipment metadata

get-exercise-template

Complete metadata for one template by ID

create-exercise-template

Create a custom exercise template

get-exercise-history

Past performed sets for a single exercise

get-exercise-templates

Read-only. Lists default and custom exercise templates with equipment and muscle metadata, paginated.

Kind: Read-only

pageSize supports up to 100 for exercise templates — a higher limit than other paginated tools. Use search-exercise-templates for a name-based lookup that scans the full catalog without paging manually.

Input parameters

page

integer

default:"1"

Page number to retrieve. Must be ≥ 1.

pageSize

integer

default:"5"

Number of templates per page. Must be between 1 and 100.

Response fields

Each template in the list includes:

Field	Type	Description
`id`	string	Template ID usable in workouts and routines
`title`	string	Display name of the exercise
`exercise_type`	string	How the exercise is tracked (see enum values)
`equipment_category`	string	Equipment type (see enum values)
`primary_muscle_group`	string	Primary muscle targeted (see enum values)
`other_muscles`	string[]	Secondary muscles involved
`is_custom`	boolean	`true` for user-created templates

get-exercise-template

Read-only. Retrieves complete metadata for a single exercise template by ID.

Kind: Read-only

Input parameters

exerciseTemplateId

string

required

The ID of the exercise template to retrieve. Must be a non-empty string. Obtain this from get-exercise-templates, search-exercise-templates, a workout, or a routine.

search-exercise-templates

Read-only. Searches the full exercise template catalog by case-insensitive title substring. Results are served from an in-memory cache that is refreshed at most once every 5 minutes, avoiding repeated full-catalog fetches.

Kind: Read-only

Always call search-exercise-templates before creating a workout or routine to resolve exercise names to their exerciseTemplateId values. This is the fastest way to find IDs without paging through the full catalog.

Input parameters

query

string

required

Case-insensitive substring to match against exercise template titles. Must be at least 1 character. For example, "bench" matches “Barbell Bench Press”, “Dumbbell Incline Bench Press”, and similar.

primaryMuscleGroup

string

Optional filter. When provided, only templates whose primary muscle group matches this value are returned. Must be one of the valid muscle group enum values.

refresh

boolean

default:"false"

Set to true to invalidate the in-memory catalog cache and re-fetch all exercise templates from the Hevy API before searching. Use this when you suspect recently created templates are missing from results.

Cache behavior

Property	Detail
TTL	5 minutes from last fetch
Capacity	One catalog (all templates) per server instance
Concurrent loads	Shared in-flight fetch — parallel requests wait on one load
Invalidation	Pass `refresh: true`, or wait for the TTL to expire
Hosted endpoint	Each Worker request gets a fresh cache — no cross-key sharing

get-exercise-templates (paginated) always bypasses the cache and fetches directly from the API. The cache is shared only by search-exercise-templates and the hevy://exercise-templates resource.

create-exercise-template

Write (mutation). Creates a custom exercise template in the Hevy account.

Kind: Write

Run search-exercise-templates first — Hevy ships hundreds of built-in templates and the exercise you need likely already exists. Retrying on failure, or reusing a title, can create duplicate templates in your catalog.

Input parameters

title

string

required

Display name of the new exercise. Must be at least 1 character.

exerciseType

string

required

How the exercise is tracked. Must be one of the valid exercise type enum values.

equipmentCategory

string

required

Equipment used for the exercise. Must be one of the valid equipment category enum values.

muscleGroup

string

required

Primary muscle group targeted. Must be one of the valid muscle group enum values.

otherMuscles

string[]

default:"[]"

Secondary muscles involved. Each value must be a valid muscle group enum value. Defaults to an empty array.

Example

{
  "title": "Reverse Nordic Curl",
  "exerciseType": "bodyweight_reps",
  "equipmentCategory": "none",
  "muscleGroup": "quadriceps",
  "otherMuscles": ["hamstrings"]
}

get-exercise-history

Read-only. Retrieves past performed sets for a single exercise template, optionally filtered by date range.

Kind: Read-only

Use get-exercise-history to analyze the performance trend for a single movement — e.g., progressive overload on bench press over 12 weeks. For complete session details, use get-workouts instead.

Input parameters

exerciseTemplateId

string

required

The ID of the exercise template whose history you want. Must be a non-empty string. Use search-exercise-templates to resolve a name to an ID.

startDate

string

Optional start of the date range. Must be an ISO 8601 datetime with timezone offset, e.g. 2024-01-01T00:00:00+00:00. Workouts before this timestamp are excluded.

endDate

string

Optional end of the date range. Must be an ISO 8601 datetime with timezone offset, e.g. 2024-03-31T23:59:59+00:00. Workouts after this timestamp are excluded.

Example

{
  "exerciseTemplateId": "A10D7A3C-B607-4B4B-B85D-5C9C86C71C63",
  "startDate": "2024-01-01T00:00:00+00:00",
  "endDate": "2024-03-31T23:59:59+00:00"
}

Valid enum values

The following enum values are the only accepted strings for the exerciseType, equipmentCategory, and muscleGroup parameters. All values are taken directly from the server source.

Exercise type (`exerciseType`)

Value	Description
`weight_reps`	Weighted exercise tracked by reps (e.g., barbell squat)
`reps_only`	Rep-counted exercise with no load (e.g., pull-ups with weight)
`bodyweight_reps`	Bodyweight exercise tracked by reps (e.g., push-ups)
`bodyweight_assisted_reps`	Assisted bodyweight exercise tracked by reps
`duration`	Timed exercise with no distance or load (e.g., plank)
`weight_duration`	Weighted timed exercise (e.g., weighted wall sit)
`distance_duration`	Distance and time exercise (e.g., running, cycling)
`short_distance_weight`	Short distance with load (e.g., sled push)

Equipment category (`equipmentCategory`)

Value	Description
`none`	No equipment / bodyweight
`barbell`	Barbell
`dumbbell`	Dumbbell
`kettlebell`	Kettlebell
`machine`	Weight machine
`plate`	Weight plate
`resistance_band`	Resistance band
`suspension`	Suspension trainer (e.g., TRX)
`other`	Other / unlisted equipment

Muscle group (`muscleGroup`)

Used for both muscleGroup (primary) and otherMuscles (secondary) fields on create-exercise-template, and for primaryMuscleGroup on search-exercise-templates.

Value	Muscle / Region
`abdominals`	Abdominals / core
`shoulders`	Shoulders (deltoids)
`biceps`	Biceps
`triceps`	Triceps
`forearms`	Forearms
`quadriceps`	Quadriceps
`hamstrings`	Hamstrings
`calves`	Calves
`glutes`	Glutes
`abductors`	Hip abductors
`adductors`	Hip adductors
`lats`	Latissimus dorsi
`upper_back`	Upper back (rhomboids)
`traps`	Trapezius
`lower_back`	Lower back / erectors
`chest`	Chest (pectorals)
`cardio`	Cardiovascular / general
`neck`	Neck
`full_body`	Full body / compound
`other`	Other / unlisted

Recommended workflow

# Discover a template ID before building a workout or routine
1. search-exercise-templates (query="squat", primaryMuscleGroup="quadriceps")
   → returns matching templates with IDs

# Inspect a specific template
2. get-exercise-template (exerciseTemplateId="...")
   → full metadata including exercise type and muscle groups

# Analyze performance over time
3. get-exercise-history (exerciseTemplateId="...", startDate="...", endDate="...")
   → all logged sets for that movement in the date window

# Create a custom exercise only if it doesn't already exist
4. create-exercise-template (title="...", exerciseType="...", ...)
   → new template added to your Hevy catalog

Overview

Workouts

Routines

Exercise Templates

Body Measurements & Account

Exercise template tools — search and manage Hevy exercises

search-exercise-templates

get-exercise-templates

get-exercise-template

create-exercise-template

get-exercise-history

get-exercise-templates

Input parameters

Response fields

get-exercise-template

Input parameters

search-exercise-templates

Input parameters

Cache behavior

create-exercise-template

Input parameters

Example

get-exercise-history

Input parameters

Example

Valid enum values

Exercise type (`exerciseType`)

Equipment category (`equipmentCategory`)

Muscle group (`muscleGroup`)

Recommended workflow

Build docs developers (and LLMs) love

Overview

Workouts

Routines

Exercise Templates

Body Measurements & Account

Documentation Index

search-exercise-templates

get-exercise-templates

get-exercise-template

create-exercise-template

get-exercise-history

​get-exercise-templates

​Input parameters

​Response fields

​get-exercise-template

​Input parameters

​search-exercise-templates

​Input parameters

​Cache behavior

​create-exercise-template

​Input parameters

​Example

​get-exercise-history

​Input parameters

​Example

​Valid enum values

​Exercise type (exerciseType)

​Equipment category (equipmentCategory)

​Muscle group (muscleGroup)

​Recommended workflow

Build docs developers (and LLMs) love

get-exercise-templates

Input parameters

Response fields

get-exercise-template

Input parameters

search-exercise-templates

Input parameters

Cache behavior

create-exercise-template

Input parameters

Example

get-exercise-history

Input parameters

Example

Valid enum values

Exercise type (`exerciseType`)

Equipment category (`equipmentCategory`)

Muscle group (`muscleGroup`)

Recommended workflow