Hevy Workout Analytics MCP Server
Provides tools for analyzing workout history exported from Hevy, allowing users to track exercise progress, volume trends, and personal records while incorporating custom training conventions and muscle group mappings.
Provides read-only SQL access to query workout datasets and retrieve database schemas, enabling complex data analysis of stored workout history.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 & ConventionsInstallation
Clone and install:
git clone <repo-url>
cd hevy-history-mcp
pip install -e .Import your Hevy data:
python scripts/import_csv.py /path/to/hevy_export.csvConfigure Claude Desktop (
~/Library/Application Support/Claude/claude_desktop_config.jsonon 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
execute_sql(query) - Run read-only SQL queries
get_schema() - Get database schema with column descriptions
get_exercise_taxonomy() - View/understand exercise-to-muscle mappings
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: isolationTracking 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 namestart_time,end_time- Workout timestampsexercise_title- Exercise nameset_index- Set numberweight_lbs,reps,distance_miles,duration_seconds- Performance metricsrpe- Rate of Perceived Exertionexercise_notes- Per-exercise notesAnd more...
Development
Run tests:
pytestFormat code:
black .
ruff check .License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
Related MCP Connectors
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Your strength-training data for any AI assistant: workouts, progress, muscle volume, routines.
Workout journal Claude and ChatGPT write to: log workouts, get a program, see your progress.
Talk to your own gym log. Reps: Gym Workout Log (repsworkout.com) is a workout log for iPhone and Android. Connect it to Claude, ChatGPT or any MCP client to read your workout history, PRs, lift progression, weekly summaries, routines and training plan, and to save routines and plans after you confirm them. It never logs a workout for you and canβt delete your history. Sign in with an e-mail code, Apple or Google; new users can create a free account while connecting, then get the app to log workouts.