Routine Tools

The Hevy HTTP MCP server provides tools for managing workout routines. Routines are templates that can be used to quickly start workouts with predefined exercises, sets, and rest periods.

get-routines

Fetch a paginated list of routines from your Hevy account.

Parameters

page

number

Page number (default: 1)

pageSize

number

Items per page (default: 5, max: 10)

Response

page

number

Current page number

page_count

number

Total number of pages available

routines

array

Array of routine objects

Show Routine object

string

Unique routine identifier

title

string

Routine title

folder_id

number | null

ID of the folder containing this routine (null if not in a folder)

updated_at

string

Last update timestamp in ISO 8601 format

created_at

string

Creation timestamp in ISO 8601 format

exercises

array

Array of exercises in this routine

Show Routine exercise object

index

number

Exercise order index

title

string

Exercise name

rest_seconds

string

Rest time between sets in seconds

notes

string

Exercise notes

exercise_template_id

string

Reference to exercise template

supersets_id

number | null

Superset group identifier (null if not in a superset)

sets

array

Array of planned sets

Show Routine set object

index

number

Set order index

type

string

Set type: normal, warmup, dropset, or failure

weight_kg

number | null

Target weight in kilograms

reps

number | null

Target number of repetitions

distance_meters

number | null

Target distance in meters (for cardio exercises)

duration_seconds

number | null

Target duration in seconds (for timed exercises)

rpe

number | null

Rate of perceived exertion (6-10 scale)

custom_metric

number | null

Custom metric value

rep_range

object | null

Target rep range for the set

Show Rep range object

start

number

Minimum target reps

end

number

Maximum target reps

Example

{
  "page": 1,
  "pageSize": 5
}

get-routine-by-id

Get a single routine by its ID.

Parameters

routineId

string

required

The routine ID

Response

Returns a single routine object with the same structure as described in get-routines.

Example

{
  "routineId": "660e8400-e29b-41d4-a716-446655440001"
}

create-routine

Create a new routine with exercises and planned sets.

Parameters

title

string

required

Routine title

folder_id

number

Folder ID to place routine in (null if not in a folder)

notes

string

Routine notes (can be null)

exercises

array

required

Array of exercises in the routine

Show Routine exercise input object

exercise_template_id

string

required

Exercise template ID (use get-exercise-templates to find valid IDs)

superset_id

number

Superset group ID (null if not in a superset)

rest_seconds

number

Rest time between sets in seconds (can be null)

notes

string

Exercise notes (can be null)

sets

array

required

Array of planned sets

Show Routine set input object

type

string

required

Set type: normal, warmup, dropset, or failure

weight_kg

number

Target weight in kilograms (can be null)

reps

number

Target number of repetitions (can be null)

distance_meters

number

Target distance in meters for cardio exercises (can be null)

duration_seconds

number

Target duration in seconds for timed exercises (can be null)

custom_metric

number

Custom metric value (can be null)

rep_range

object

Target rep range for the set (can be null)

Show Rep range object

start

number

required

Minimum target reps

end

number

required

Maximum target reps

Response

Returns the created routine object.

Example

{
  "title": "Pull Day",
  "folder_id": 1,
  "notes": "Back and biceps focus",
  "exercises": [
    {
      "exercise_template_id": "770e8400-e29b-41d4-a716-446655440003",
      "superset_id": null,
      "rest_seconds": 120,
      "notes": "Full stretch at bottom",
      "sets": [
        {
          "type": "warmup",
          "weight_kg": 50,
          "reps": 10
        },
        {
          "type": "normal",
          "weight_kg": 80,
          "rep_range": {
            "start": 8,
            "end": 12
          }
        },
        {
          "type": "normal",
          "weight_kg": 80,
          "rep_range": {
            "start": 8,
            "end": 12
          }
        }
      ]
    },
    {
      "exercise_template_id": "770e8400-e29b-41d4-a716-446655440004",
      "superset_id": 1,
      "rest_seconds": 90,
      "notes": "Superset with face pulls",
      "sets": [
        {
          "type": "normal",
          "weight_kg": 40,
          "rep_range": {
            "start": 12,
            "end": 15
          }
        }
      ]
    },
    {
      "exercise_template_id": "770e8400-e29b-41d4-a716-446655440005",
      "superset_id": 1,
      "rest_seconds": 90,
      "notes": "Superset with rows",
      "sets": [
        {
          "type": "normal",
          "weight_kg": 30,
          "rep_range": {
            "start": 15,
            "end": 20
          }
        }
      ]
    }
  ]
}

update-routine

Update an existing routine by its ID.

Parameters

routineId

string

required

The routine ID to update

title

string

required

Updated routine title

notes

string

Updated routine notes (can be null)

exercises

array

required

Updated exercises (same structure as create-routine)

Response

Returns the updated routine object.

Example

{
  "routineId": "aa0e8400-e29b-41d4-a716-446655440050",
  "title": "Pull Day - Updated",
  "notes": "Back and biceps with extra volume",
  "exercises": [
    {
      "exercise_template_id": "770e8400-e29b-41d4-a716-446655440003",
      "superset_id": null,
      "rest_seconds": 120,
      "notes": "Full stretch at bottom",
      "sets": [
        {
          "type": "warmup",
          "weight_kg": 50,
          "reps": 10
        },
        {
          "type": "normal",
          "weight_kg": 80,
          "rep_range": {
            "start": 8,
            "end": 12
          }
        },
        {
          "type": "normal",
          "weight_kg": 80,
          "rep_range": {
            "start": 8,
            "end": 12
          }
        },
        {
          "type": "normal",
          "weight_kg": 80,
          "rep_range": {
            "start": 8,
            "end": 12
          }
        }
      ]
    }
  ]
}

MCP Tools

Types

get-routines

Parameters

Response

Example

get-routine-by-id

Parameters

Response

Example

create-routine

Parameters

Response

Example

update-routine

Parameters

Response

Example

Build docs developers (and LLMs) love

MCP Tools

Types

​get-routines

​Parameters

​Response

​Example

​get-routine-by-id

​Parameters

​Response

​Example

​create-routine

​Parameters

​Response

​Example

​update-routine

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

get-routines

Parameters

Response

Example

get-routine-by-id

Parameters

Response

Example

create-routine

Parameters

Response

Example

update-routine

Parameters

Response

Example