A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants to access and manage workout data, routines, exercise templates, and more through the Hevy API (requires PRO subscription).

• Workout Management: Fetch, create, and update workouts
• Routine Management: Access and manage workout routines
• Exercise Templates: Browse available exercise templates
• Folder Organization: Manage routine folders

• Node.js (v20 or higher)
• npm or yarn
• A Hevy API key

To install hevy-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @chrisdoc/hevy-mcp --client claude

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies
npm install

# Create .env file from sample
cp .env.sample .env
# Edit .env and add your Hevy API key

To use this MCP server with Cursor, you need to update your ~/.cursor/mcp.json file by adding the following configuration:

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

Make sure to replace your-api-key-here with your actual Hevy API key.

Create a .env file in the project root with the following content:

HEVY_API_KEY=your_hevy_api_key_here

Replace your_hevy_api_key_here with your actual Hevy API key.

npm run dev

This starts the MCP server in development mode with hot reloading.

npm run build
npm start

The server implements the following MCP tools:

• get-workouts: Fetch and format workout data
• get-workout: Get a single workout by ID
• create-workout: Create a new workout
• update-workout: Update an existing workout
• get-workout-count: Get the total count of workouts
• get-workout-events: Get workout update/delete events

• get-routines: Fetch and format routine data
• create-routine: Create a new routine
• update-routine: Update an existing routine
• get-routine: Get a single routine by ID

• get-exercise-templates: Fetch exercise templates
• get-exercise-template: Get a template by ID

• get-routine-folders: Fetch routine folders
• create-routine-folder: Create a new folder
• get-routine-folder: Get a folder by ID

hevy-mcp/
├── .env                   # Environment variables (API keys)
├── src/
│   ├── index.ts           # Main entry point
│   ├── tools/             # Directory for MCP tool implementations
│   │   ├── workouts.ts    # Workout-related tools
│   │   ├── routines.ts    # Routine-related tools
│   │   ├── templates.ts   # Exercise template tools
│   │   └── folders.ts     # Routine folder tools
│   ├── generated/         # API client (generated code)
│   │   ├── client/        # Kiota-generated client
│   └── utils/             # Helper utilities
│       ├── formatters.ts  # Data formatting helpers
│       └── validators.ts  # Input validation helpers
├── scripts/               # Build and utility scripts
└── tests/                 # Test suite

This project uses Biome for code formatting and linting:

npm run check

The API client is generated from the OpenAPI specification using Kiota:

npm run export-specs
npm run build:client

This project is licensed under the MIT License - see the LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.

• Model Context Protocol for the MCP SDK
• Hevy for their fitness tracking platform and API