Hevy MCP
An MCP (Model Context Protocol) server for Hevy — the workout tracking app. Connects any MCP-compatible AI client (Claude, Cursor, etc.) to your Hevy account, letting it read your workouts, routines, and exercises, or log new ones on your behalf.
Built with FastMCP and async httpx.
Requirements
- Python 3.11+
- uv package manager
- Hevy Pro subscription (for API access)
- Hevy API key (Settings > API in the Hevy app)
Setup
# Clone and install
git clone https://github.com/zachsai/hevy-mcp.git
cd hevy-mcp
uv sync
# Configure
cp env.example .env
# Edit .env and add your HEVY_API_KEY
# Run locally
./run.sh
The server starts on http://localhost:8000 with streamable-HTTP transport.
Tools
Read
| Tool | Description |
|---|---|
get_workout_count | Total number of logged workouts |
list_workouts | List workouts with pagination |
get_workout | Full workout details (exercises, sets, weights) |
list_routines | List saved routines |
get_routine | Full routine details |
search_exercises | Search exercise templates by name |
Write
| Tool | Description |
|---|---|
create_workout | Log a new workout |
update_workout | Update an existing workout |
create_routine | Create a new routine |
update_routine | Update an existing routine |
Architecture
hevy_mcp/
├── server.py # FastMCP server, Pydantic models, tool definitions
└── utils/
├── auth.py # API key from environment
└── hevy.py # Async HTTP client for Hevy API v1
- Auth: Static API key via
api-keyheader (no OAuth complexity) - HTTP client: async httpx with pagination support
- Models: Pydantic BaseModel for all tool inputs/outputs
Deployment
Docker (any platform)
Includes a Dockerfile for container deployment. The server reads PORT from the environment and exposes a /health_check endpoint.
docker build -t hevy-mcp .
docker run -e HEVY_API_KEY=your_key -e PORT=8080 hevy-mcp
Railway
This project is set up for one-click deployment on Railway. See RAILWAY_DEPLOY.md for the full step-by-step playbook covering:
- Creating the Railway project
- Deploying the Docker container
- Setting environment variables (
HEVY_API_KEY,ENVIRONMENT) - Generating a public domain
- Verifying the deployment (health check + MCP handshake)
The playbook documents the exact Railway MCP tool calls and parameters, so it can be followed manually or used as a reference for building an automated deployment skill with the Railway MCP server.
Development
uv run ruff check --fix # Lint
uv run ruff format # Format
uv run python tests/test_http.py # Integration test (HTTP)
uv run python tests/test_stdio.py # Integration test (stdio)