MCP resources exposed by Hevy MCP

Hevy MCP registers four MCP resources that return JSON data at well-known URIs. Clients can read them directly without tool calls — useful for bootstrapping context at the start of a session or fetching reference data that does not change often. Each resource uses the hevy:// URI scheme and returns application/json.

user-profile

URI: hevy://user Returns the authenticated user’s ID, display name, and public profile URL. The data is fetched from the Hevy /v1/user endpoint on every read. Response shape:

{
  "id": "abc123",
  "username": "jane_doe",
  "profile_url": "https://hevy.com/user/jane_doe"
}

workout-count

URI: hevy://workout-count Returns the total number of workouts logged in the account. Response shape:

{
  "count": 142
}

exercise-templates

URI: hevy://exercise-templates Returns the full formatted exercise template catalog. All pages are fetched and concatenated before the resource is returned, so the response includes every template in the account — both Hevy built-ins and any custom templates you have created. The catalog is served from the same in-memory cache shared with the search-exercise-templates tool (see Cache behavior below). Response shape:

[
  {
    "id": "template_001",
    "title": "Barbell Back Squat",
    "type": "weight_reps",
    "primary_muscle_group": "quads",
    "secondary_muscle_groups": ["glutes", "hamstrings"],
    "equipment": "barbell",
    "is_custom": false
  }
]

routine-folders

URI: hevy://routine-folders Returns the full formatted list of routine folders, including both default folders and any custom folders you have created. All pages are fetched before the resource is returned. Response shape:

[
  {
    "id": "folder_001",
    "title": "Push / Pull / Legs",
    "created_at": "2024-06-01T10:00:00Z",
    "updated_at": "2024-06-01T10:00:00Z"
  }
]

Cache behavior for exercise-templates

The hevy://exercise-templates resource and the search-exercise-templates tool share a server-scoped in-memory catalog cache with the following properties:

TTL: Cached entries live for 5 minutes. After expiry the next read triggers a fresh full-catalog fetch.
Capacity: The cache holds at most one catalog entry at a time.
Concurrent requests: Concurrent requests for the catalog share a single in-flight fetch rather than issuing duplicate API calls.
Per-request isolation (hosted Worker): Each hosted Worker request gets a fresh cache instance. There is no cross-key or cross-client sharing on the hosted endpoint.
Force refresh: Call search-exercise-templates with refresh: true to invalidate the cache immediately and re-fetch the full catalog.

The hosted Cloudflare Worker creates a fresh server instance per request, so the exercise template cache is not shared across different clients or API keys on the hosted endpoint. Each request starts with an empty cache and fetches from the Hevy API as needed.

Accessing resources

Resources use the hevy:// URI scheme and can be read by any MCP client that supports resource reads. In clients that expose an explicit resource browser (such as some IDE extensions), the four Hevy resources appear in the resource list automatically after the server connects. In assistant-based clients, you can ask the assistant to read a resource by name — for example:

“Read the hevy://exercise-templates resource and find all templates that target the chest.”

The assistant will issue a resource read, receive the JSON payload, and answer from the returned data.

Prompts

Use guided prompts to coordinate multi-step training analysis and workout creation.

Tools Overview

Browse all 25 tools available in Hevy MCP.

Get Started

Connecting Clients

Guides

MCP resources exposed by Hevy MCP

user-profile

workout-count

exercise-templates

routine-folders

Cache behavior for exercise-templates

Accessing resources

Prompts

Tools Overview

​user-profile

​workout-count

​exercise-templates

​routine-folders

​Cache behavior for exercise-templates

​Accessing resources

Prompts

Tools Overview

user-profile

workout-count

exercise-templates

routine-folders

Cache behavior for exercise-templates

Accessing resources