Skip to main content
Glama

hevy-mcp: Model Context Protocol Server for Hevy Fitness API

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).

Features

  • 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
  • Webhook Subscriptions: Create, view, and delete webhook subscriptions for workout events

Prerequisites

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

Installation

Installing via Smithery

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

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

Manual Installation

# 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

Integration with Cursor

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.

Configuration

Create a .env file in the project root (you can copy from .env.sample) with the following content:

HEVY_API_KEY=your_hevy_api_key_here

Replace your_hevy_api_key_here with your actual Hevy API key.

Transport Modes

The MCP server supports two transport modes:

Stdio Transport (Default)

The default mode uses stdio transport, which is suitable for integration with MCP clients like Claude Desktop and Cursor:

npm start # or node dist/index.js

HTTP Transport

The server can also run in HTTP mode for remote access or web-based integrations:

# Start in HTTP mode npm start -- --http # or node dist/index.js --http # Using environment variable MCP_TRANSPORT=http npm start
HTTP Configuration

The HTTP transport can be configured using environment variables:

# Transport mode MCP_TRANSPORT=http # HTTP server configuration MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 # DNS rebinding protection (recommended for production) MCP_DNS_REBINDING_PROTECTION=true MCP_ALLOWED_HOSTS=127.0.0.1,localhost
HTTP Endpoints

When running in HTTP mode, the following endpoints are available:

  • POST /mcp - MCP client-to-server communication
  • GET /mcp - Server-to-client notifications (SSE)
  • DELETE /mcp - Session termination
  • GET /health - Health check endpoint
Session Management

The HTTP transport includes session management for stateful connections. Each client session is identified by a unique session ID that must be included in the mcp-session-id header for subsequent requests.

Usage

Development

npm run dev

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

Production

npm run build npm start

Available MCP Tools

The server implements the following MCP tools for interacting with the Hevy API:

Workout 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

Routine Tools

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

Exercise Template Tools

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

Routine Folder Tools

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

Webhook Tools

  • get-webhook-subscription: Get the current webhook subscription
  • create-webhook-subscription: Create a new webhook subscription
  • delete-webhook-subscription: Delete the current webhook subscription

Project Structure

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 │ │ └── webhooks.ts # Webhook subscription tools │ ├── generated/ # API client (generated code) │ │ ├── client/ # Kubb-generated client │ │ │ ├── api/ # API client methods │ │ │ ├── types/ # TypeScript types │ │ │ ├── schemas/ # Zod schemas │ │ │ └── mocks/ # Mock data │ └── utils/ # Helper utilities │ ├── formatters.ts # Data formatting helpers │ └── validators.ts # Input validation helpers ├── scripts/ # Build and utility scripts └── tests/ # Test suite ├── integration/ # Integration tests with real API │ └── hevy-mcp.integration.test.ts # MCP server integration tests

Development Guide

Code Style

This project uses Biome for code formatting and linting:

npm run check

Testing

Run All Tests

To run all tests (unit and integration), use:

npm test

Note: If the HEVY_API_KEY environment variable is set, integration tests will also run. If not, only unit tests will run.

Run Only Unit Tests

To run only unit tests (excluding integration tests):

npx vitest run --exclude tests/integration/**

Or with coverage:

npx vitest run --coverage --exclude tests/integration/**
Run Only Integration Tests

To run only the integration tests (requires a valid HEVY_API_KEY):

npx vitest run tests/integration

Note: The integration tests will fail if the HEVY_API_KEY environment variable is not set. This is by design to ensure that the tests are always run with a valid API key.

GitHub Actions Configuration

For GitHub Actions:

  1. Unit tests will always run on every push and pull request
  2. Integration tests will only run if the HEVY_API_KEY secret is set in the repository settings

To set up the HEVY_API_KEY secret:

  1. Go to your GitHub repository
  2. Click on "Settings" > "Secrets and variables" > "Actions"
  3. Click on "New repository secret"
  4. Set the name to HEVY_API_KEY and the value to your Hevy API key
  5. Click "Add secret"

If the secret is not set, the integration tests step will be skipped with a message indicating that the API key is missing.

Generating API Client

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

npm run export-specs npm run build:client

Kubb generates TypeScript types, API clients, Zod schemas, and mock data from the OpenAPI specification.

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Acknowledgements

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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).

  1. Features
    1. Prerequisites
      1. Installation
        1. Installing via Smithery
        2. Manual Installation
        3. Integration with Cursor
      2. Configuration
        1. Usage
          1. Development
          2. Production
        2. Available MCP Tools
          1. Workout Tools
          2. Routine Tools
          3. Exercise Template Tools
          4. Routine Folder Tools
        3. Project Structure
          1. Development
            1. Code Style
            2. Generating API Client
          2. License
            1. Contributing
              1. Acknowledgements

                Related MCP Servers

                • -
                  security
                  A
                  license
                  -
                  quality
                  A high-performance Model Context Protocol (MCP) server designed for large language models, enabling real-time communication between AI models and applications with support for session management and intelligent tool registration.
                  Last updated -
                  2
                  MIT License
                • A
                  security
                  F
                  license
                  A
                  quality
                  An all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.
                  Last updated -
                  3
                  • Apple
                  • Linux
                • -
                  security
                  A
                  license
                  -
                  quality
                  A server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.
                  Last updated -
                  169
                  1
                  MIT License
                • -
                  security
                  F
                  license
                  -
                  quality
                  A Model Context Protocol (MCP) Server that provides unified access to multiple external APIs (weather, news, financial data) through a single, consistent interface for AI agents and LLMs.
                  Last updated -
                  1

                View all related MCP servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrisdoc/hevy-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server