Hevy健身数据API工具

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?

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:

1. Open the branch's completed CI run under the repository's Actions page.
2. Download the hevy-linux-x86_64-<commit-sha> artifact.
3. 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

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

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):

1. Start the server:
   复制

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

2. 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

Measurement Tools

User Tools

Routine Tools

Routine Folder Tools

Exercise Template Tools

Routine Search

Training Summary

Webhook Tools

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