The Hevy MCP server enables AI assistants to interact with the Hevy fitness tracking app API for comprehensive fitness data management:
Workout Management: Fetch, create, update, and track workouts with detailed exercise data
Routine Management: Access, create, update, and organize workout routines
Exercise Templates: Browse and retrieve both standard and custom exercise templates
Folder Organization: Create and manage folders to categorize routines effectively
Utilized for code formatting and linting in the development process of the MCP server.
Used for environment variable configuration to store the Hevy API key.
Used for version control of the MCP server codebase.
Hosts the repository for the MCP server codebase.
Provides tools for accessing and managing workout data, routines, exercise templates, and folders through the Hevy fitness app API, enabling workout tracking and fitness management capabilities.
Required as a runtime environment (v20 or higher) for running the MCP server.
Used as a package manager for installing and managing dependencies of the MCP server.
Provides badge for license information in the README.
Supported as an alternative package manager for installing and managing dependencies.
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:
Manual Installation
Integration with Cursor
To use this MCP server with Cursor, you need to update your ~/.cursor/mcp.json
file by adding the following configuration:
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:
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:
HTTP Transport
The server can also run in HTTP mode for remote access or web-based integrations:
HTTP Configuration
The HTTP transport can be configured using environment variables:
HTTP Endpoints
When running in HTTP mode, the following endpoints are available:
POST /mcp
- MCP client-to-server communicationGET /mcp
- Server-to-client notifications (SSE)DELETE /mcp
- Session terminationGET /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
This starts the MCP server in development mode with hot reloading.
Production
Available MCP Tools
The server implements the following MCP tools for interacting with the Hevy API:
Workout Tools
get-workouts
: Fetch and format workout dataget-workout
: Get a single workout by IDcreate-workout
: Create a new workoutupdate-workout
: Update an existing workoutget-workout-count
: Get the total count of workoutsget-workout-events
: Get workout update/delete events
Routine Tools
get-routines
: Fetch and format routine datacreate-routine
: Create a new routineupdate-routine
: Update an existing routineget-routine-by-id
: Get a single routine by ID using direct endpoint
Exercise Template Tools
get-exercise-templates
: Fetch exercise templatesget-exercise-template
: Get a template by ID
Routine Folder Tools
get-routine-folders
: Fetch routine folderscreate-routine-folder
: Create a new folderget-routine-folder
: Get a folder by ID
Webhook Tools
get-webhook-subscription
: Get the current webhook subscriptioncreate-webhook-subscription
: Create a new webhook subscriptiondelete-webhook-subscription
: Delete the current webhook subscription
Project Structure
Development Guide
Code Style
This project uses Biome for code formatting and linting:
Testing
Run All Tests
To run all tests (unit and integration), use:
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):
Or with coverage:
Run Only Integration Tests
To run only the integration tests (requires a valid HEVY_API_KEY
):
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:
- Unit tests will always run on every push and pull request
- 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:
- Go to your GitHub repository
- Click on "Settings" > "Secrets and variables" > "Actions"
- Click on "New repository secret"
- Set the name to
HEVY_API_KEY
and the value to your Hevy API key - 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:
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
- Model Context Protocol for the MCP SDK
- Hevy for their fitness tracking platform and API
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.
Tools
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).
Related MCP Servers
- -securityAlicense-qualityA 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 -2MIT License
- AsecurityFlicenseAqualityAn 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
- -securityAlicense-qualityA server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.Last updated -1691MIT License
- -securityFlicense-qualityA 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