{
  "markdown": "# hevy-mcp-remote: Hosted / gateway-ready MCP for Hevy Fitness\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Build Docker image](https://github.com/rwestergren/hevy-mcp/actions/workflows/docker.yml/badge.svg)](https://github.com/rwestergren/hevy-mcp/actions/workflows/docker.yml)\n[![ghcr.io](https://img.shields.io/badge/ghcr.io-rwestergren%2Fhevy--mcp-blue)](https://github.com/rwestergren/hevy-mcp/pkgs/container/hevy-mcp)\n\n> **Fork notice.** This is an independently-maintained fork of [`chrisdoc/hevy-mcp`](https://github.com/chrisdoc/hevy-mcp), repackaged for multi-tenant MCP gateways. It ships the same Hevy tools wrapped in [supergateway](https://github.com/supercorp-ai/supergateway) as an OCI image that speaks MCP streamable-HTTP over HTTP, instead of stdio. Use the upstream `hevy-mcp` npm package for local/stdio use in Claude Desktop, Cursor, etc.\n\nA Model Context Protocol (MCP) server for the [Hevy fitness tracking app](https://www.hevyapp.com/), packaged as a supergateway-wrapped OCI image for hosting behind an MCP gateway. Exposes MCP streamable-HTTP on `/mcp` and health on `/healthz`; reads `HEVY_API_KEY` from the container environment.\n\n---\n\n## 📋 Table of Contents\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n  - [Claude Desktop Configuration](#claude-desktop-configuration)\n  - [Cursor Configuration](#cursor-configuration)\n- [Why hevy-mcp?](#why-hevy-mcp)\n- [Configuration](#configuration)\n- [Available MCP Tools](#available-mcp-tools)\n- [Development & Contributing](#development--contributing)\n\n---\n\n## 🚀 Features\n\n- **Workout Management**: Fetch, create, and update workouts.\n- **Routine Management**: Access and manage workout routines.\n- **Exercise Templates**: Browse available exercise templates with in-memory caching.\n- **Folder Organization**: Manage routine folders.\n- **Webhook Subscriptions**: Create, view, and delete webhook subscriptions for workout events.\n\n---\n\n## 🏁 Quick Start\n\nPick the workflow that fits your setup:\n\n| Scenario              | Command                                     | Requirements               |\n| :-------------------- | :------------------------------------------ | :------------------------- |\n| **One-off stdio run** | `HEVY_API_KEY=sk_live... npx -y hevy-mcp`   | Node.js ≥ 24, Hevy API key |\n| **Local development** | `npm install && npm run build && npm start` | `.env` with `HEVY_API_KEY` |\n\n---\n\n## 🛠️ Prerequisites\n\n- **Node.js**: v24 or higher (strongly recommended to use the exact version pinned in `.nvmrc`).\n- **npm**: v10 or higher.\n- **Hevy API key**: Required for all operations (available with Hevy PRO).\n\n---\n\n## 📦 Installation\n\n### Run via npx (Recommended)\n\nYou can launch the server directly without cloning:\n\n```bash\nHEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp\n```\n\n### Manual Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/chrisdoc/hevy-mcp.git\ncd hevy-mcp\n\n# Install dependencies\nnpm install\n\n# Create .env and add your keys\ncp .env.sample .env\n# Edit .env and add your HEVY_API_KEY\n```\n\n---\n\n## 🔗 Integration\n\n### Claude Desktop Configuration\n\nTo use this server with Claude Desktop, add the following to your `claude_desktop_config.json`:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"hevy-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"hevy-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"HEVY_API_KEY\": \"sk_live_your_key_here\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### Cursor Configuration\n\nAdd this server under `\"mcpServers\"` in `~/.cursor/mcp.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"hevy-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"hevy-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"HEVY_API_KEY\": \"your-api-key-here\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n---\n\n## ✨ Why hevy-mcp?\n\n- 🚀 **High Performance**: Built with the **Oxc** toolchain (`oxlint`/`oxfmt`) for near-instant linting and formatting.\n- 🛡️ **Type Safety**: Fully type-safe implementation using **Zod** and **Kubb**-generated API clients.\n- 📉 **Observability**: Built-in **Sentry** monitoring for error tracking and performance profiling.\n- ⚡ **Optimized**: Includes in-memory caching for exercise templates to reduce API latency.\n\n---\n\n## ⚙️ Configuration\n\nSupply your Hevy API key via:\n\n1. **Environment Variable**: `HEVY_API_KEY` (in `.env` or system environment).\n2. **CLI Argument**: `--hevy-api-key=your_key` (after `--` in npm scripts).\n\n```env\n# Example .env\nHEVY_API_KEY=your_hevy_api_key_here\n```\n\n### 📡 Sentry Monitoring\n\n`hevy-mcp` includes Sentry monitoring to observe errors and usage in production. It initializes `@sentry/node` with tracing enabled and PII collection disabled by default.\n\n---\n\n## 🐳 Running behind an MCP gateway (supergateway contract)\n\nThe MCP server itself speaks **stdio only**. For multi-tenant gateway\ndeployments (e.g. [mcp-gateway-poc](https://github.com/rwestergren/mcp-gateway-poc)),\nthis repo ships a `Dockerfile` that wraps the stdio binary with\n[supergateway](https://github.com/supercorp-ai/supergateway) so a single\ncontainer exposes MCP streamable-HTTP.\n\nThe image follows the same contract every gateway-hosted MCP uses:\n\n- MCP streamable-HTTP on `0.0.0.0:$PORT` at `/mcp`\n- Health endpoint at `/healthz`\n- Stateful sessions (`Mcp-Session-Id` honored)\n- `HEVY_API_KEY` is read from the container environment and passed to the\n  spawned stdio child\n\nImages are published to `ghcr.io/rwestergren/hevy-mcp` from `main` and from\nany manually cut GitHub release. Build locally with:\n\n```bash\ndocker build -t hevy-mcp:local .\ndocker run --rm -e HEVY_API_KEY=sk_live_... -p 8080:8080 hevy-mcp:local\ncurl http://localhost:8080/healthz\n```\n\nEnd users running `hevy-mcp` directly should use the stdio/`npx` flow above;\nthe Docker image is aimed at gateway operators, not individual clients.\n\n---\n\n## 🛠️ Available MCP Tools\n\n| Category      | Tools                                                                                                        |\n| :------------ | :----------------------------------------------------------------------------------------------------------- |\n| **Workouts**  | `get-workouts`, `get-workout`, `create-workout`, `update-workout`, `get-workout-count`, `get-workout-events` |\n| **Routines**  | `get-routines`, `get-routine-by-id`, `create-routine`, `update-routine`                                      |\n| **Templates** | `get-exercise-templates`, `get-exercise-template`, `search-exercise-templates`                               |\n| **Folders**   | `get-routine-folders`, `get-routine-folder`, `create-routine-folder`                                         |\n| **Webhooks**  | `get-webhook-subscription`, `create-webhook-subscription`, `delete-webhook-subscription`                     |\n\n---\n\n## 👨‍💻 Development & Contributing\n\n### Quick Commands\n\n- **Build**: `npm run build`\n- **Lint/Format**: `npm run check` (uses oxlint/oxfmt)\n- **Unit Tests**: `npx vitest run --exclude tests/integration/**`\n- **Full Test Suite**: `npm test` (requires `HEVY_API_KEY`)\n\nFor a detailed senior engineer guide, please refer to [AGENTS.md](./AGENTS.md).\n\n### API Client Generation\n\nThe API client is automatically generated from the OpenAPI spec using [Kubb](https://kubb.dev/):\n\n```bash\nnpm run build:client\n```\n\n---\n\n## 📄 License & Acknowledgements\n\n- **License**: [MIT](./LICENSE)\n- **Credits**: [Model Context Protocol](https://github.com/modelcontextprotocol), [Hevy Fitness](https://www.hevyapp.com/).\n\n---\n\n**Contributions are welcome!** Please open an issue or PR for any major changes.\n",
  "bytes": 7661,
  "sha": "a627dab2182497ad6682388059f7ab5abcb103e2686f479183e2833d6d158b63",
  "repo_slug": "rwestergren/hevy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rwestergren_hevy_mcp_remote_00909545/readme"
}