Which integrations are available for this server?

Enables interaction with Hevy workout data, allowing users to list and retrieve workout and routine details, search for exercises, and log or update new workouts and routines.

How do I use Hevy MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hevy MCP Show me my last 3 workouts and their details." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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-key header (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)