# 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**:
```bash
git clone <repo-url>
cd hevy-history-mcp
pip install -e .
```

2. **Import your Hevy data**:
```bash
python scripts/import_csv.py /path/to/hevy_export.csv
```

3. **Configure Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
  "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:

```yaml
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:

```yaml
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:
```bash
pytest
```

Format code:
```bash
black .
ruff check .
```

## License

MIT