Skip to main content
Glama
Sign In
hevy-mcp-server

hevy-mcp-server

by VReippainen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Hevy MCP Server

A TypeScript Node.js server that connects your Hevy workout data to Language Models via Model Context Protocol (MCP). The server fetches data from the Hevy API and provides tools for accessing your workout history, exercise progress, and personal records.

What is MCP?

Model Context Protocol (MCP) is a standard that allows LLMs like Claude to integrate with external data sources and tools. This MCP server enables AI assistants to access and analyze your Hevy workout data.

Related MCP server: hevy-mcp

Available Tools

This MCP server provides the following tools:

  • get-workouts: Get workouts between start and end dates. Returns workouts in descending order of date with duration and volume stats. Max 10 workouts.

  • get-exercise-progress-by-ids: Track progress for specific exercises over time, filtered by date range. Returns also records per reps.

  • get-exercises: Get comprehensive exercise data sorted by frequency of use, with optional filtering by name and date range. Returns also actual and estimated 1RM.

  • get-routines: Retrieve your saved workout routines

Workout Prompt Builder

The server includes a smart workout prompt builder that:

  • Analyzes your most frequently used exercises and their estimated 1RMs

  • Lists your saved workout routines with detailed exercise information

  • Helps AI assistants create personalized workout recommendations based on your history

Resource Documentation

The server provides comprehensive documentation of all available tools and their parameters through a dedicated resource endpoint. This documentation includes:

  • Detailed parameter descriptions

  • Valid parameter ranges and defaults

  • Example usage scenarios

Obtaining Your Hevy API Key

To get your Hevy API key, visit the Hevy API Documentation and follow the authentication instructions. You'll need to sign up for API access through the Hevy developer portal.

Adding to Cursor

To add this MCP server to Cursor, update your ~/.cursor/mcp.json file with the following configuration:

"hevy-mcp-server": {
  "command": "npx",
  "args": ["-y", "@vreippainen/hevy-mcp-server", "--stdio"],
  "env": {
    "HEVY_API_KEY": "your-api-key-here"
  }
}

Replace your-api-key-here with your actual Hevy API key.

Technical Documentation

For detailed technical information about installation, configuration, running the server, API endpoints, service methods, and project structure, see TECHNICAL.md.

Release Process

This project uses semantic-release for automated versioning and package publishing. We follow the Conventional Commits specification for commit messages.

Available Tools

4 tools
get-exercise-progress-by-idsA

Get progress history for specific exercises between start and end dates. Returns exercise data including weights, reps, and sets for each workout. Results are ordered by date descending. Useful for tracking progress over time for particular exercises.

Example: { "exerciseIds": ["bench-press-123", "squat-456"], // Required: Array of exercise IDs "limit": 5, // Optional: Number of workouts (0-10, default: 10) "startDate": "2024-01-01T00:00:00Z", // Optional: Filter after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Filter before this date }

Inputs: exerciseIds (required), limit, startDate, endDate.

get-exercisesA

Get comprehensive exercise data including frequency of use, categorization, and metadata. Results are sorted by usage frequency. Supports filtering by name search and date range.

Example: { "searchTerm": "bench press", // Optional: Filter exercises by name "excludeUnused": true, // Optional: Skip never-performed exercises (default: true) "startDate": "2024-01-01T00:00:00Z", // Optional: Consider usage after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Consider usage before this date }

Inputs: searchTerm, excludeUnused, startDate, endDate.

get-routinesB

Get user's saved workout routines. Returns all custom and preset routines with their full exercise details, including sets, reps, and rest periods.

Example: {} // No parameters required

Inputs: no named parameters.

get-workoutsA

Get workouts between start and end dates. Returns all workouts if no dates are provided. Returns workouts in descending order of date and limits the number of workouts returned. Max 10 workouts.

Example: { "limit": 5, // Optional: Number of workouts (1-10, default: 10) "startDate": "2024-01-01T00:00:00Z", // Optional: Filter workouts after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Filter workouts before this date }

Inputs: limit, startDate, endDate.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct data type (exercises, exercise progress, routines, workouts) with no overlap in purpose or output.

    Naming Consistency5/5

    All tools follow a consistent get-<noun> pattern with hyphens, using descriptive plural nouns.

    Tool Count5/5

    Four tools cover the core read-only operations for a fitness tracking server without being too few or too many.

    Completeness2/5

    Only read operations are provided; there are no tools to create or update workouts, exercises, or routines, which are typical for a workout app.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • hevy-mcp

      Alexisb1988
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, analyze, create, and update Hevy workout data, including workouts, routines, exercises, and body measurements, through the Model Context Protocol.
      2,615 npm
      MIT

    • hevy-mcp-server

      adamdavies1915
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with the Hevy fitness tracking API, allowing users to log workouts, manage routines, browse exercises, and track fitness progress through natural language.
      15 npm
      MIT

    • GymTimer MCP Server

      elkno
      A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to access and modify a user's real GymTimer workout and nutrition data stored in private iCloud, allowing natural-language queries about training history and the creation of workout templates and meal plans.
      21
      MIT