Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/zachsai/hevy-mcp.git
cd hevy-mcp
uv syncRegister it in Claude Code
claude mcp add -e "HEVY_API_KEY=${HEVY_API_KEY}" hevy-mcp -- uv run /path/to/hevy-mcp/server.pyReplace any placeholder paths in the command with the real path on your machine.
HEVY_API_KEY+ 1 optionalMake your agent remember this setup
hevy-mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Read workout history and exercise details
- List and manage saved workout routines
- Log new workout sessions via natural language
- Update existing workout and routine data
- Search exercise templates
Tools 10
get_workout_countReturns the total number of logged workoutslist_workoutsList workouts with paginationget_workoutGet full workout details including exercises, sets, and weightslist_routinesList saved workout routinesget_routineGet full details for a specific routinesearch_exercisesSearch exercise templates by namecreate_workoutLog a new workout sessionupdate_workoutUpdate an existing workout entrycreate_routineCreate a new workout routineupdate_routineUpdate an existing workout routineEnvironment Variables
HEVY_API_KEYrequiredAPI key obtained from Hevy app settingsPORTPort for the server to listen onTry it
Original README from zachsai/hevy-mcp
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)