hevy-mcp / hevy-cli (Rust)

Rust tools for the Hevy fitness tracking app and its API:

hevy-mcp: a Model Context Protocol server for MCP-capable clients such as Claude Desktop, Cursor, LobeChat, LibreChat, and IDE plugins.
hevy-cli: a direct command-line client for scripts, shell automation, and agent skills that should run one command and exit.

Both binaries use the same typed Rust Hevy API client and require no Node or Python runtime.

Requires a Hevy PRO subscription to access the Hevy API.

Which Should I Use?

Use case	Use this	Why
Your AI client supports MCP tools and can keep a tool server configured	`hevy-mcp`	Exposes Hevy operations as MCP tools over stdio or streamable HTTP
You want one-off shell commands, scripts, cron jobs, or CI automation	`hevy-cli`	Runs a single command, prints JSON, and exits
You are packaging an agent skill around Hevy access	`hevy-cli` + `skills/hevy`	Skills can invoke the binary directly without running an MCP server
You want HTTP/SSE access for a hosted or web client	`hevy-mcp --transport streamable-http`	Provides an MCP endpoint at `/mcp`

Features

Workout Management — Fetch, create, and update workouts
Routine Management — Access and manage workout routines and folders
Exercise Templates — Browse available templates; create custom ones
Exercise History — Query past sets for any exercise template
Body Measurements — List, read, create, and patch dated measurements
User Info — Authenticated profile (ID, display name, URL)
Webhook Subscriptions — Create, view, and delete webhook subscriptions
Dual Transport — Runs over stdio (default) or streamable-http (SSE)
Direct CLI — hevy-cli provides JSON-first commands and guarded writes with --confirm (workouts, routines + routines search, folders, templates + templates search, exercises, measurements, user, summary, webhooks, export, auth)
Agent Skill — skills/hevy documents how agents should call hevy-cli

Quick Start

Install `hevy-mcp` via Binary

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Brandon168/hevy-mcp-rust/master/install.sh | sh

Windows (PowerShell): Download the hevy-mcp-windows-x86_64.zip from the Releases page, extract it, and place the hevy-mcp.exe in your PATH, or run it directly:

.\hevy-mcp.exe --help

Install `hevy-cli` via Release Asset

Download the matching hevy-cli-* archive from the Releases page, extract it, and place hevy-cli on your PATH.

Example for Linux x86_64:

curl -L -o hevy-cli-linux-x86_64.tar.gz \
  https://github.com/Brandon168/hevy-mcp-rust/releases/latest/download/hevy-cli-linux-x86_64.tar.gz
tar -xzf hevy-cli-linux-x86_64.tar.gz
chmod +x hevy-cli
sudo mv hevy-cli /usr/local/bin/
hevy-cli --help

Download CI-Built Binaries

Every branch push, pull request, and manual CI dispatch builds Linux x86_64 archives for both binaries and uploads them as a workflow artifact. This is the preferred way to test a branch build before creating a release:

Open the branch's completed CI run under the repository's Actions page.
Download the hevy-linux-x86_64-<commit-sha> artifact.
Verify dist/SHA256SUMS, then extract the matching archive from dist/.

From a shell, the same artifact can be downloaded with:

gh run download <run-id> \
  --repo Brandon168/hevy-mcp-rust \
  --name hevy-linux-x86_64-<commit-sha>

Run from Source

git clone https://github.com/Brandon168/hevy-mcp-rust.git
cd hevy-mcp-rust
HEVY_API_KEY=sk_live_... cargo run --release --bin hevy-mcp
HEVY_API_KEY=sk_live_... cargo run --release --bin hevy-cli -- auth test

Prerequisites

Hevy PRO Subscription — Required to access the Hevy API.
Hevy API Key — Generate an API key in your Hevy account.
Rust 1.75+ — Only required if building from source (pre-compiled binaries have no dependencies).

Platform support: Runs on macOS, Linux, and Windows. The binary is fully cross-platform — cargo build --release produces a native executable on each platform (hevy-mcp.exe on Windows). Note: macOS and Linux are tested and work well. Windows and WSL should work but are currently untested; feedback is welcome!

Installation & Configuration

API Key

Provide your Hevy API key via environment variable or CLI flag:

# Environment variable (recommended)
export HEVY_API_KEY=sk_live_your_key_here

# Or as a CLI flag
./hevy-mcp --hevy-api-key=sk_live_your_key_here

You can also place it in a .env file in the project root (loaded automatically at startup):

HEVY_API_KEY=sk_live_your_key_here

Never commit your .env file or API keys to source control.

`hevy-cli`

Use hevy-cli for direct shell usage, automation, or agent skills. It does not start an MCP server.

hevy-cli auth test
hevy-cli workouts list --page 1 --page-size 10
hevy-cli workouts get --id <workout_id>
hevy-cli export workouts --weeks 3 --full
hevy-cli export routine-bundle --routine-id <routine_id> --weeks 3

Write commands require --confirm:

hevy-cli routines create --input routine.json --confirm
hevy-cli measurements create --date 2026-04-21 --input measurement.json --confirm
hevy-cli summary --weeks 4
hevy-cli webhooks delete --confirm

Hevy stores kilograms. For pound-based work, input JSON may use weight_lb instead of weight_kg (converted exactly, never rounded), and the global --lb flag adds weight_lb beside every weight_kg in output, so you can read a write back and confirm clean values:

hevy-cli routines create --input routine.json --confirm   # sets use "weight_lb": 15
hevy-cli --lb routines get --id <routine_id>

To install the local skill wrapper after building a release binary, pass the destination expected by your agent runtime:

cargo build --release --bin hevy-cli
./scripts/install-hevy-skill.sh /path/to/agent/skills/hevy

`hevy-mcp`

Use hevy-mcp when an MCP-capable client should discover and call Hevy tools. It runs as a server over stdio by default or over streamable HTTP when requested. All 25 tools are listed under Available MCP Tools below.

Transport Mode

Flag	Default	Description
`--transport stdio`	✅ default	JSON-RPC over stdin/stdout — works with Claude Desktop, Cursor, etc.
`--transport streamable-http`	—	HTTP server on `--port` (default 3000) at `/mcp`
`--port <PORT>`	`3000`	Port for streamable-http mode

All flags can also be set via environment variables: MCP_TRANSPORT, MCP_PORT.

Integration with AI Clients

Cursor / Claude Desktop (Stdio)

Add to ~/.cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "hevy-mcp": {
      "command": "/path/to/hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Streamable HTTP (SSE)

When using hevy-mcp with a client that supports the streamable-http transport (such as LobeChat, LibreChat, or IDE plugins):

Start the server:

hevy-mcp --transport streamable-http --port 3333

Configure Client:
- Endpoint URL: http://localhost:3333/mcp
- Type: Streamable HTTP (or SSE)

Note: The server supports a full MCP over SSE implementation. The result of the initialize call is streamed via SSE, while subsequent requests use standard HTTP POST to the manifest endpoint.

Available MCP Tools

Workout Tools

Tool	Description
`get-workouts`	Paginated list of workouts (newest first)
`get-workout`	Single workout by ID
`get-workout-count`	Total number of workouts on account
`get-workout-events`	Paginated workout update/delete events since a date
`create-workout`	Log a new workout with exercises and sets
`update-workout`	Patch metadata only; exercises preserved (is_private required)
`replace-workout-exercises`	Replace all exercises/sets; metadata preserved (is_private required)

Measurement Tools

Tool	Description
`get-body-measurements`	Paginated list of dated body measurements
`get-body-measurement`	Single measurement by date (`YYYY-MM-DD`)
`create-body-measurement`	Create a measurement for a new date (409 on duplicates)
`update-body-measurement`	Patch numeric fields on an existing date (read-then-PUT)

Routine Tools

Tool	Description
`get-routines`	Paginated list of routines
`get-routine`	Single routine by ID
`create-routine`	Create a new workout routine
`update-routine`	Update an existing routine

Routine Folder Tools

Tool	Description
`get-routine-folders`	Paginated list of routine folders
`get-routine-folder`	Single folder by ID
`create-routine-folder`	Create a new routine folder

Exercise Template Tools

Tool	Description
`get-exercise-templates`	Paginated list of exercise templates
`get-exercise-template`	Single template by ID
`search-exercise-templates`	Case-insensitive title substring search (full scan)
`get-exercise-history`	Past sets for a template (with optional date range)
`create-exercise-template`	Create a custom exercise template

Routine Search

Tool	Description
`search-routines`	Case-insensitive title search, compact hits, `--limit` 1–100

Training Summary

Tool	Description
`get-training-summary`	1–12 weeks of workout/volume/session totals + measurement trend endpoints

Webhook Tools

Tool	Description
`get-webhook-subscription`	View current webhook subscription
`create-webhook-subscription`	Register a new webhook URL
`delete-webhook-subscription`	Remove current webhook subscription

Development

Project Structure

hevy-mcp-rust/
├── Cargo.toml              # Package manifest and dependencies
├── .env                    # Local API key (not committed)
├── skills/
│   └── hevy/               # Agent skill wrapper for hevy-cli
├── scripts/
│   └── install-hevy-skill.sh
├── src/
│   ├── main.rs             # hevy-mcp entry point
│   ├── lib.rs              # Library root (exports client, tools, types)
│   ├── client.rs           # HevyClient — typed REST API wrapper
│   ├── bin/
│   │   └── hevy-cli.rs     # Direct command-line client
│   ├── types.rs            # Serde + JsonSchema typed structs
│   └── tools.rs            # HevyTools — all 20 MCP tool implementations
├── tests/
│   ├── cli_test.rs         # hevy-cli command tests
│   ├── integration_test.rs # Full E2E tests (stdio & streamable-http)
│   ├── client_test.rs      # Unit tests for HevyClient using wiremock
│   └── deserialize_test.rs # Verification of API response parsing
└── openapi-spec.json       # Cleaned Hevy API specification

Testing & Verification

We maintain a high bar for reliability. Before submitting changes, always run:

cargo test

Mock Testing: We use wiremock in client_test.rs to verify HTTP interactions without hitting the live API.
Integration Handshakes: integration_test.rs spawns the binary to verify the full MCP lifecycle over both Stdio and SSE.
Schema Validation: Unit tests in tools.rs ensure JSON Schemas remain compatible with the reference implementation.

AI Developer Note: When adding new tools or changing types, ensure you update the corresponding mock in client_test.rs and verify deserialization in deserialize_test.rs. Use HEVY_BASE_URL to point the client to your mock server.

License

This project is licensed under the MIT License.

Acknowledgements

Model Context Protocol for the MCP SDK and specification
Hevy for their fitness tracking platform and API
chrisdoc/hevy-mcp — the original TypeScript implementation this was ported from

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
scripts		scripts
skills/hevy		skills/hevy
src		src
tests		tests
.cursorrules		.cursorrules
.env.sample		.env.sample
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
openapi-spec.json		openapi-spec.json

Latest commit

History

Folders and files

Repository files navigation

hevy-mcp / hevy-cli (Rust)

Which Should I Use?

Features

Quick Start

Install hevy-mcp via Binary

Install hevy-cli via Release Asset

Download CI-Built Binaries

Run from Source

Prerequisites

Installation & Configuration

API Key

hevy-cli

hevy-mcp

Transport Mode

Integration with AI Clients

Cursor / Claude Desktop (Stdio)

Streamable HTTP (SSE)

Available MCP Tools

Workout Tools

Measurement Tools

User Tools

Routine Tools

Routine Folder Tools

Exercise Template Tools

Routine Search

Training Summary

Webhook Tools

Development

Project Structure

Testing & Verification

License

Acknowledgements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Install `hevy-mcp` via Binary

Install `hevy-cli` via Release Asset

`hevy-cli`

`hevy-mcp`