Hevy Workout Analytics MCP Server

An MCP (Model Context Protocol) server that provides Claude with SQL access to your Hevy workout data, plus rich context about your personal training conventions.

Features

• 📊 SQL Access: Query your workout history with full SQL capabilities
• 🏋️ Exercise Taxonomy: Customizable muscle group mappings for exercises
• 📝 Personal Conventions: Track your specific rules (form resets, RPE usage, etc.)
• 🔒 Read-Only: Safe SQL execution with no write permissions
• 🎯 Smart Analysis: Let Claude write complex queries to answer nuanced questions

Architecture

Hevy CSV Export → SQLite Database → MCP Server → Claude
                                          ↓
                                    Taxonomy & Conventions

Installation

1. Clone and install:

git clone <repo-url>
cd hevy-history-mcp
pip install -e .

2. Import your Hevy data:

python scripts/import_csv.py /path/to/hevy_export.csv

3. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hevy-history": {
      "command": "python",
      "args": ["-m", "hevy_mcp.server"],
      "env": {
        "HEVY_DB_PATH": "/path/to/hevy.db"
      }
    }
  }
}

Usage

Example Questions for Claude

• "Which triceps exercises progressed best in the last 6 months?"
• "Which exercises have plateaued?"
• "What are my PRs for compound lifts?"
• "Show volume trends for chest exercises"
• "Account for form resets when analyzing bench press progress"

Available Tools

1. execute_sql(query) - Run read-only SQL queries
2. get_schema() - Get database schema with column descriptions
3. get_exercise_taxonomy() - View/understand exercise-to-muscle mappings
4. get_tracking_conventions() - Read your personal tracking rules

Configuration

Exercise Taxonomy (taxonomy.yaml)

Map exercises to muscle groups and specify compound movement credit:

exercises:
  "Bench Press (Barbell)":
    primary: [chest]
    secondary: [triceps, front_delts]
    category: compound
  "Tricep Pushdown (Cable)":
    primary: [triceps]
    category: isolation

Tracking Conventions (conventions.yaml)

Document your personal rules for analysis:

form_resets:
  - exercise: "Bench Press (Barbell)"
    date: "2024-03-15"
    reason: "Reset to focus on form, reduced weight by 20%"

rpe_usage:
  - "I track RPE consistently for main compound lifts"
  - "Isolation work RPE is less consistent"

tracking_notes:
  - "Superset_id groups exercises done back-to-back"
  - "I rest-pause sets are marked in exercise_notes"

Database Schema

The importer creates a workout_sets table with all Hevy CSV columns:

• title - Workout name
• start_time, end_time - Workout timestamps
• exercise_title - Exercise name
• set_index - Set number
• weight_lbs, reps, distance_miles, duration_seconds - Performance metrics
• rpe - Rate of Perceived Exertion
• exercise_notes - Per-exercise notes
• And more...

Development

Run tests:

pytest

Format code:

black .
ruff check .

License

MIT