# Quick Start Guide
Get up and running with Hevy History MCP in 5 minutes!
## Step 1: Install Dependencies
```bash
# Install the package in development mode
pip install -e .
```
## Step 2: Export Your Hevy Data
1. Open the Hevy app on your phone
2. Go to Settings → Account → Export Data
3. Choose CSV format
4. Email or save the CSV file to your computer
## Step 3: Import to SQLite
```bash
# Import your CSV file
python scripts/import_csv.py ~/Downloads/hevy_workout_data.csv
# This creates hevy.db in the current directory
# Or specify a custom location:
python scripts/import_csv.py ~/Downloads/hevy_workout_data.csv --db ~/hevy.db
```
## Step 4: Customize Your Configuration
### Edit Exercise Taxonomy
```bash
# Edit the taxonomy file to match your exercises
nano config/taxonomy.yaml
```
Add any exercises that aren't already listed:
```yaml
exercises:
"Your Custom Exercise":
primary: [muscle_group]
secondary: [other_muscle]
category: compound # or isolation
```
### Edit Tracking Conventions
```bash
# Add your personal training context
nano config/conventions.yaml
```
Document important events like:
- Form resets
- Deload periods
- Injuries
- Equipment changes
## Step 5: Configure Claude Desktop
Add to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"hevy-history": {
"command": "python",
"args": ["-m", "hevy_mcp.server"],
"env": {
"HEVY_DB_PATH": "/absolute/path/to/your/hevy.db"
}
}
}
}
```
**Important**: Use absolute paths! Replace `/absolute/path/to/your/hevy.db` with your actual database location.
## Step 6: Restart Claude Desktop
1. Quit Claude Desktop completely
2. Relaunch it
3. Look for the 🔨 tools icon in the bottom right to confirm the MCP server is connected
## Step 7: Start Asking Questions!
Try these example prompts in Claude:
### Basic Exploration
- "What exercises do I have data for?"
- "Show me my recent workouts"
- "What's the structure of the workout data?"
### Progress Analysis
- "Which triceps exercises have I progressed on most in the last 6 months?"
- "What are my PRs for bench press?"
- "Which exercises have plateaued?"
### Volume Trends
- "Show me my weekly training volume trend"
- "Which muscle groups am I training the most?"
- "How has my squat volume changed over time?"
### Smart Analysis
- "Find exercises where I've made the best progress, accounting for the form reset on bench press in March 2024"
- "What's my training frequency for each exercise?"
- "Show me my best sets by total load (weight × reps)"
## Troubleshooting
### Server not showing up in Claude
1. Check the config file has valid JSON
2. Verify the paths are absolute, not relative
3. Check Claude Desktop logs (Help → View Logs)
4. Make sure `hevy.db` exists at the specified path
### Database not found
```bash
# Verify the database exists
ls -lh hevy.db
# Check you're using absolute path in config
pwd # See current directory
```
### Import errors
```bash
# Make sure your CSV has the correct columns
head -1 your_export.csv
# Expected columns:
# title,start_time,end_time,description,exercise_title,superset_id,
# exercise_notes,set_index,set_type,weight_lbs,reps,distance_miles,
# duration_seconds,rpe
```
### Python module not found
```bash
# Reinstall in development mode
pip install -e .
# Or install with dependencies explicitly
pip install mcp pyyaml
```
## Next Steps
- Read `EXAMPLE_QUERIES.md` to learn SQL patterns
- Customize `config/taxonomy.yaml` with your exercises
- Update `config/conventions.yaml` with your training history
- Ask Claude to analyze your specific training questions!
## Updating Data
When you have new workouts:
```bash
# Re-export from Hevy app
# Re-import (this replaces all data)
python scripts/import_csv.py ~/Downloads/new_hevy_export.csv
```
The import script clears and re-imports all data, so your database is always fresh.
## Tips
1. **Use Claude to write SQL**: You don't need to know SQL! Just ask Claude questions in plain English.
2. **Provide context**: Mention form resets, injuries, or other context in your questions for better analysis.
3. **Check the taxonomy**: Run `get_exercise_taxonomy()` to see which exercises Claude knows about.
4. **Iterate on queries**: Ask Claude to refine queries based on results.
5. **Export results**: Ask Claude to format results as markdown tables or charts.
Happy training! 🏋️
