Skip to content
Conduit

mcp server

hevy-analytics

Shared Hevy analytics core with MCP and CLI adapters for automation

Kymylyy/hevy-analyticscommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "hevy-analytics": {
      "command": "uvx",
      "args": [
        "hevy-analytics"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

hevy-analytics

CI

hevy-analytics is a shared Hevy analytics core with two adapters:

  • hevy-mcp for LLM and MCP-compatible clients
  • hevy-cli for cronjobs, automation, and dashboard ingestion

It exposes focused tools for exercise search, progression analysis, workout summaries, volume distribution, fatigue signals, accessory suggestions, training logging, and routine inspection.

Architecture

  • hevy_analytics.service and related modules contain the analytics core.
  • hevy_analytics.mcp_server renders the existing markdown contract for MCP clients.
  • hevy_analytics.cli exposes the same capabilities for automation with json or markdown output.

Features

  • search_exercise(name)
  • exercise_progression(name, weeks=12)
  • recent_workouts(days=7, limit=30)
  • weekly_volume(weeks=4)
  • fatigue_check()
  • suggest_accessories()
  • training_log(days=30)
  • top_exercises(days=30, limit=5)
  • get_routines()

MCP tools return markdown with a stable section contract:

  • ## Summary
  • ## Data Window
  • ## Details
  • ## Notes

Requirements

  • Python 3.11+
  • Hevy API key

Quickstart

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
export HEVY_API_KEY="your-key"

MCP

hevy-mcp

Compatibility wrapper:

python3 run_hevy_mcp.py

CLI

hevy-cli recent-workouts --days 14 --output json --pretty
hevy-cli weekly-volume --weeks 6 --output markdown
hevy-cli training-log --days 30 --out data/training-log.json

MCP Configuration Example

{
  "mcpServers": {
    "hevy": {
      "command": "python3",
      "args": ["/absolute/path/to/run_hevy_mcp.py"],
      "env": {
        "HEVY_API_KEY": "your-key"
      }
    }
  }
}

CLI Output

  • Default output is json for automation and cronjobs.
  • --output markdown preserves the human-readable MCP-style rendering.
  • --out PATH writes snapshots directly to a file for downstream ingestion.
  • --fail-on-no-data exits non-zero when a command returns status=no_data.
  • Exit codes: 0 for success, 1 for errors, 3 for no_data when --fail-on-no-data is set.

Cron Example

0 6 * * * cd /absolute/path/to/hevy-mcp && /absolute/path/to/.venv/bin/hevy-cli recent-workouts --days 2 --out data/recent-workouts.json --pretty
15 6 * * * cd /absolute/path/to/hevy-mcp && /absolute/path/to/.venv/bin/hevy-cli weekly-volume --weeks 4 --out data/weekly-volume.json --pretty

Constraints

  • Read-only integration (GET-oriented API usage).
  • Input guards:
    • days: 1..365
    • weeks: 1..52
    • limit: ≥ 1
    • name: minimum 2 characters
  • Fuzzy matching uses difflib (no external fuzzy dependency).

Migration Notes

  • Python package changed from hevy_mcp to hevy_analytics.
  • Distribution name changed from hevy-mcp to hevy-analytics.
  • hevy-mcp remains the MCP executable for compatibility.
  • New automation entrypoint: hevy-cli.
  • run_hevy_mcp.py remains as a thin compatibility wrapper.

Development

Run checks in this order:

python3 -m ruff check .
python3 -m mypy src tests
python3 -m pytest

GitHub Actions runs these checks on push and pull_request.

Security

If you find a security issue, follow /SECURITY.md. Do not open public issues for secrets or vulnerabilities.

License

MIT. See /LICENSE.

↑↓ navigate openesc close