Hevy History

Provides Claude SQL access to Hevy workout data with taxonomy and conventions for advanced analysis.

python

0

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can connect Claude to your Hevy workout data through an MCP server that exposes your workout history as read-only SQL. This lets Claude perform complex queries, correlate exercises with your personal conventions, and retrieve structured insights without risking data modification. The server reads your Hevy CSV exports, builds a local SQLite database, and serves a safe, query-only interface you can use from Claude.

How to use

You interact with the Hevy History MCP Server by connecting Claude to the local MCP endpoint that the server provides. The server runs as a read-only SQL bridge to your Hevy workout data. Use Claude to ask questions like which exercises progressed most over a period, which movements show plateau behavior, or how form resets affect bench progress. You can also request schema details and understand how exercises map to muscle groups through the built-in taxonomy.

How to install

Prerequisites: you need Python installed on your machine. You will clone the project, install the package, import your data, and configure Claude to connect to the MCP server.

# 1. Clone the MCP server repository and install
git clone <repo-url>
cd hevy-history-mcp
pip install -e .

# 2. Import your Hevy data from CSV export
python scripts/import_csv.py /path/to/hevy_export.csv

Configure Claude Desktop to point at the MCP server. Use the macOS path shown and provide the runtime command and environment variable that points to your local database.

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

Additional configuration and data definitions

You can customize how exercises map to muscle groups and document your tracking conventions to influence Claude’s analysis. The server reads two YAML configuration files to refine analysis.

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

# conventions.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"

Available tools

execute_sql

Run read-only SQL queries against the local database to fetch workout data and derived metrics.

get_schema

Retrieve the database schema with descriptions for each column.

get_exercise_taxonomy

View the mapping of exercises to muscle groups and movement categories.

get_tracking_conventions

Read your personal conventions for form resets, RPE usage, and related notes.