hevy-mcp-interface: Hevy Fitness API Interaction Layer

This implementation serves as an MCP server dedicated to bridging AI/LLM contexts with the underlying data structures of the Hevy fitness application through its RESTful API interface. It facilitates comprehensive read/write operations on user-generated fitness logs, prescribed routines, and foundational exercise definitions. Note: Full API access typically necessitates a Hevy PRO subscription.

Core Capabilities

• Workout Ledger Interaction: Retrieve historical sessions, initiate new session logs, and perform modifications on existing entries.
• Routine Blueprint Management: Full lifecycle management (CRUD) for personalized workout schemas.
• Exercise Catalog Access: Query the comprehensive repository of standardized exercise definitions.
• Organizational Structuring: Manage hierarchical groupings (folders) for saved routines.
• Event Notification Subscriptions: Establish declarative mechanisms to receive real-time alerts concerning workout state changes.

System Requirements

• Runtime Environment: Node.js (version 20 or newer)
• Package Manager: npm or yarn
• Authorization Credential: A valid Hevy API key

Installation Procedures

Deployment via Smithery

For streamlined, automated deployment compatible with Claude Desktop interfaces using Smithery:

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

Local Setup

bash

Obtain the source code repository

git clone https://github.com/chrisdoc/hevy-mcp.git cd hevy-mcp

Install required packages

npm install

Prepare configuration file from template

cp .env.sample .env

Populate .env with your authorized Hevy API credential

Integration with Cursor IDE

To enable this server within the Cursor environment, modify your local MCP manifest (~/.cursor/mcp.json) by appending the following service definition:

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

Ensure that your-api-key-here is substituted with your actual, valid access token.

Credential Configuration

The Hevy API authorization token can be supplied via two mechanisms:

1. Environment Variable: Set HEVY_API_KEY in the execution environment.
2. Command-Line Parameter: Passed directly during server invocation (e.g., --hevy-api-key=key_value when using npm scripts).

If utilizing the environment variable approach, populate the .env file (copied from .env.sample) in the project root:

env HEVY_API_KEY=your_actual_hevy_api_key_value

Alternatively, to bypass environment variable setting and use a command argument for the key:

bash npm start -- --hevy-api-key=your_hevy_api_key_value

For operation over HTTP transport:

bash npm start -- --http --hevy-api-key=your_hevy_api_key_value

Communication Protocols

The MCP gateway supports distinct modes for client communication:

Standard I/O Transport (Default)

This synchronous method is the preferred channel for local client integrations, such as Claude Desktop or Cursor:

bash npm start

OR

node dist/index.js

HyperText Transfer Protocol (HTTP) Transport

This mode enables remote access or web-based client interactions:

bash

Initiate HTTP mode (using environmental variable for key)

npm start -- --http

Initiate HTTP mode (using CLI argument for key)

npm start -- --http --hevy-api-key=your_api_key_value

Direct execution

node dist/index.js --http --hevy-api-key=your_api_key_value

Set transport via environment variable

MCP_TRANSPORT=http npm start

HTTP Service Configuration

HTTP transport parameters are modulated via specific environment variables:

env

Set transport mode

MCP_TRANSPORT=http

Network binding details

MCP_HTTP_HOST=127.0.0.1 PORT=3000

Security measure against DNS rebinding (recommended for production usage)

MCP_DNS_REBINDING_PROTECTION=true MCP_ALLOWED_HOSTS=127.0.0.1,localhost

HTTP Service Endpoints

When the server operates in HTTP context, the following resource access points are exposed:

• POST /mcp: Primary channel for MCP client requests to the server.
• GET /mcp: Server-to-client streaming channel (Server-Sent Events) for asynchronous notifications.
• DELETE /mcp: Endpoint to signal graceful session termination.
• GET /health: Status check endpoint to verify operational readiness.

Session Lifecycle Management

The HTTP transport incorporates stateful session tracking. Every initiating client connection is assigned a unique session identifier, which must be included in the mcp-session-id request header for all subsequent interactions within that session.

Operational Guide

Development Workflow

bash npm run dev

This command initiates the server in a monitored state, featuring live reloading capabilities for rapid iteration.

Production Deployment

bash npm run build npm start

Containerization (Docker)

The repository includes a Dockerfile enabling deployment via containers. Images are built and published to GitHub Container Registry (GHCR) as part of the automated CI/CD pipeline.

Utilizing Pre-built Artifacts

Pull and run the most current stable image:

bash docker run -d \ --name hevy-mcp \ -e HEVY_API_KEY=your_api_key_here \ -p 3000:3000 \ ghcr.io/chrisdoc/hevy-mcp:latest

Alternative: Pass the key as a runtime argument instead of an environment variable

docker run -d \ --name hevy-mcp \ -p 3000:3000 \ ghcr.io/chrisdoc/hevy-mcp:latest \ hevy-api-key=your_api_key_here

Local Image Construction

bash

Build the container image locally

docker build -t hevy-mcp .

Execute the local container

docker run -d \ --name hevy-mcp \ -e HEVY_API_KEY=your_api_key_here \ -p 3000:3000 \ hevy-mcp

With CLI argument for key

docker run -d \ --name hevy-mcp \ -p 3000:3000 \ hevy-mcp \ hevy-api-key=your_api_key_here

Docker Compose Blueprint

yaml version: '3.8' services: hevy-mcp: image: ghcr.io/chrisdoc/hevy-mcp:latest environment: - HEVY_API_KEY=your_api_key_here - MCP_TRANSPORT=http - MCP_HTTP_HOST=0.0.0.0 - PORT=3000 ports: - "3000:3000" restart: unless-stopped

Available Image Designations

• latest: The most recent stable release artifact.
• main: The bleeding-edge build derived from the primary development branch.
• v1.8.8, v1.8, v1: Specific semantic version tags marking official releases.

Exposed MCP Functionality

The server exposes the following specialized toolsets for external invocation against the Hevy data layer:

Session/Log Tools

• get-workouts: Retrieve and format batch workout records.
• get-workout: Fetch a singular workout instance via its unique identifier.
• create-workout: Post a new session log to the user's history.
• update-workout: Modify parameters of an existing workout entry.
• get-workout-count: Determine the aggregate number of completed workouts.
• get-workout-events: Access change stream records for workout modifications/deletions.

Routine Schema Tools

• get-routines: Retrieve and standardize user-defined workout schedules.
• create-routine: Define a novel, reusable workout structure.
• update-routine: Revise the configuration of an extant routine.
• get-routine-by-id: Direct retrieval of a routine based on its ID.

Exercise Reference Tools

• get-exercise-templates: List available canonical exercises.
• get-exercise-template: Obtain details for a specific exercise ID.

Schedule Organization Tools

• get-routine-folders: Access the hierarchical organization structure for routines.
• create-routine-folder: Establish a new organizational grouping.
• get-routine-folder: Retrieve a specific folder's metadata.

Notification Channel Tools

• get-webhook-subscription: Inspect the current active notification listener configuration.
• create-webhook-subscription: Define a new event notification webhook.
• delete-webhook-subscription: Decommission the existing notification subscription.

Internal Project Architecture

plaintext hevy-mcp/ ├── .env # Runtime configuration variables (API secrets) ├── src/ │ ├── index.ts # Server bootstrap and main execution flow │ ├── tools/ # Directory housing all exposed MCP tool implementations │ │ ├── workouts.ts # Logic for workout data operations │ │ ├── routines.ts # Logic for routine structure manipulation │ │ ├── templates.ts # Logic for exercise template querying │ │ ├── folders.ts # Logic for routine grouping management │ │ └── webhooks.ts # Logic for managing push notification endpoints │ ├── generated/ # Artifacts generated from OpenAPI specifications │ │ ├── client/ # Code generated by Kubb │ │ │ ├── api/ # Low-level API method wrappers │ │ │ ├── types/ # Generated TypeScript interfaces │ │ │ ├── schemas/ # Zod validation schemas │ │ │ └── mocks/ # Static data samples for testing │ └── utils/ # Auxiliary helper functions │ ├── formatters.ts # Data transformation utilities │ └── validators.ts # Input sanitation and verification helpers ├── scripts/ # Build automation and supplementary execution scripts └── tests/ # Comprehensive testing suite ├── integration/ # Tests requiring live API connectivity │ └── hevy-mcp.integration.test.ts # End-to-end integration verification

Development Practices

Code Quality Enforcement

This repository mandates code consistency using the Biome toolchain for linting and formatting:

bash npm run check

Testing Regimen

Comprehensive Test Execution

Execute all validation routines (both isolated unit tests and external integration tests):

bash npm test

Constraint: Integration tests are conditionally executed. They will only run if the HEVY_API_KEY environment variable has been successfully provisioned.

Isolating Unit Tests

To run tests strictly confined to the application logic, excluding external API calls:

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

To generate a report on code coverage during unit testing:

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

Isolating Integration Tests

To execute only the tests that validate connectivity and data exchange with the live Hevy endpoint (requires a valid HEVY_API_KEY):

bash npx vitest run tests/integration

Caveat: Integration tests are designed to fail gracefully if the required API key credential is absent, serving as a guardrail for production readiness.

GitHub Actions Deployment Logic

Workflow execution is configured as follows:

1. Unit tests execute unconditionally upon every push or pull request submission.
2. Integration tests are gated; they proceed only if the repository secret named HEVY_API_KEY is present and configured.

To configure the necessary secret in your GitHub repository:

1. Navigate to the repository interface.
2. Select "Settings" $\rightarrow$ "Secrets and variables" $\rightarrow$ "Actions".
3. Select "New repository secret".
4. Define the name as HEVY_API_KEY and input your personal Hevy access key as the value.
5. Finalize by clicking "Add secret".

If this secret is omitted, the step responsible for running integration verification will be skipped, logging a notification regarding the missing credential.

API Client Generation

The client-side interface proxies are automatically generated using Kubb from the defined OpenAPI specification:

bash npm run export-specs npm run build:client

Kubb facilitates the creation of TypeScript type definitions, the API client wrapper functions, standardized data validation schemas, and necessary mock data fixtures directly from the specification.

Licensing

This intellectual property is distributed under the terms of the MIT License (refer to the LICENSE file for exhaustive terms).

Collaboration

Contributions are highly encouraged. Kindly submit a Pull Request. For substantial modifications or architectural shifts, please initiate a discussion by opening an issue beforehand.

Attributions

• The foundational Model Context Protocol SDK.
• The Hevy platform for developing the fitness ecosystem and exposing its API.

WIKIPEDIA: Business management tools encompass the methodologies, computational solutions, applications, and control systems utilized by enterprises to navigate evolving market dynamics, secure competitive positioning, and elevate overall organizational efficacy.

== Synthesis == Management tools can be segmented according to departmental focus and functional aspect, such as process control, planning, record-keeping, employee coordination, decision support, and performance oversight. A functional categorization typically addresses these general operational components:

• Mechanisms for initial data capture and validation across all functional units.
• Systems dedicated to supervising and refining core business workflows.
• Tools designed for aggregating data and facilitating strategic choices. Contemporary business tooling has undergone rapid modernization due to accelerated technological progress, making optimal tool selection for any given corporate scenario increasingly complex. This stems from persistent pressure to reduce overhead, maximize revenue generation, accurately discern customer requirements, and deliver products that satisfy those demands precisely as specified. In this context, executive leadership should adopt a strategic perspective on selecting and implementing management tools, rather than defaulting to the newest available technology. Over-reliance on unadjusted, off-the-shelf solutions frequently results in operational instability. Therefore, business management tools must be chosen with deliberation and subsequently tailored to the specific operational mandate of the organization, not the reverse.

== Prominent Selections == A 2013 analysis by Bain & Company illustrated the global deployment of business tools, reflecting how their measured results align with regional necessities, market conditions, and corporate downturns. The ten most frequently adopted instruments included:

Strategic planning Customer relationship management Employee engagement surveys Benchmarking Balanced scorecard Core competency Outsourcing Change management programs Supply chain management Mission statement and vision statement Market segmentation Total quality management

== Enterprise Software Applications == Software, defined as a suite of computational programs employed by organizational personnel to execute diverse operational tasks, is termed business software or an enterprise application. These applications aim to enhance productivity levels, quantify performance metrics, and execute various company functions with high fidelity. The evolution progressed from foundational Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) frameworks, later incorporating Customer Relationship Management (CRM) capabilities, culminating in the modern paradigm of cloud-based business management suites. While a quantifiable link exists between IT investment and corporate performance, two elements are critical multipliers: the efficiency of the deployment process and the rigor applied during the selection and customization phase of the chosen technology.

== Resources for Small and Medium Enterprises (SMEs) == Tools specifically engineered for SMEs are vital as they offer pathways for cost optimization and operational scaling...