hevy

The Hevy Fitness MCP Server exposes a set of tools that allow an AI assistant to interact with your Hevy account via the MCP protocol. It provides access to workouts, routines, exercises, and organizational features so chat-based assistants can log activity, fetch progress, and manage plans without leaving the chat interface. Core capabilities include creating and querying workouts with detailed exercise data, retrieving routine and exercise templates, organizing content into folders, and syncing changes through event retrieval. Use this server to enable conversational agents to plan workouts, review progress, and tailor training programs based on your Hevy data.

To connect from an AI client, point the MCP client at the server endpoint and use the defined tool names (e.g., get_workouts, create_workout, get_routines, get_exercise_templates). The server handles input validation, calls to the Hevy API, and returns structured results suitable for chat-based workflows. For deployment, you can run the MCP server locally or deploy to a cloud environment; the server reads your Hevy API key at runtime and communicates with Hevy to fulfill tool requests.

Prerequisites:

• Node.js (LTS) installed on your machine
• npm (comes with Node.js) or pnpm/yarn if you prefer
• A Hevy Pro subscription and a Hevy API key

Installation steps:

1. Clone the repository: git clone https://github.com/tomtorggler/hevy-mcp-server.git cd hevy-mcp-server

2. Install dependencies: npm install

3. Configure your Hevy API key (set as an environment variable or use a secret management approach):

   • Option A (env var): export HEVY_API_KEY=your_hevy_api_key
   • Option B (in runtime env): set HEVY_API_KEY in your hosting environment

4. Run the MCP server locally for development: npm run dev

5. (Optional) Build for production if your setup requires it, and run the built server according to your hosting environment.

Notes:

• The server expects HEVY_API_KEY to authenticate with the Hevy API. Ensure this is kept secret in production.
• If deploying to a cloud provider or Cloudflare Workers, follow their deployment guidance and provide the same environment variable.

Tips and considerations:

• Ensure you have a valid Hevy Pro subscription and an active API key before using the MCP server.
• In production, restrict access to your MCP endpoint and manage secrets (HEVY_API_KEY) securely.
• When upgrading Hevy API access or changing scopes, update the API client wrappers accordingly in src/lib/client.ts and validate inputs with Zod as described in the repo.
• If you encounter rate limits or authentication errors, verify your Hevy API key is active and that the key has the required permissions for the requested operations.
• For debugging, use the provided usage examples in the README to craft valid MCP tool invocations and inspect returned results for expected shapes.