# 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
