Hevy MCP Server

A Model Context Protocol (MCP) server that provides access to workout data from the Hevy fitness tracking app. This server enables AI assistants to query workout history, exercise details, routines, and other fitness data through natural language conversations.

Features

• Workout History: Retrieve paginated workout history with detailed exercise and set information
• Exercise Templates: Access exercise definitions including muscle groups and exercise types
• Exercise History: Track progress for specific exercises over time with optional date filtering
• Workout Routines: View and analyze planned workout routines
• Comprehensive Error Handling: Clear error messages and robust API error handling
• Async Operations: Built with async/await for efficient I/O operations
• Multiple Transport Modes: Supports both stdio and HTTP/SSE (Server-Sent Events)
• Test Mode: Built-in mock data mode for testing without a real API key

Installation

Using uvx (Recommended)

The easiest way to use this MCP server is with uvx:

uvx hevy-mcp-server

Using pip

pip install hevy-mcp-server

Development Installation

Clone the repository and install in development mode:

git clone <repository-url>
cd hevy-mcp-server
pip install -e ".[dev]"

Configuration

Obtaining a Hevy API Key

1. Visit https://hevyapp.com/api-key
2. Log in with your Hevy account
3. Generate an API key (UUID format)
4. Copy the API key for use in configuration

Environment Variables

Create a .env file or set environment variables:

# Required
HEVY_API_KEY=your_api_key_here

# Optional (with defaults)
HEVY_API_BASE_URL=https://api.hevyapp.com
HEVY_REQUEST_TIMEOUT=30
LOG_LEVEL=INFO

See .env.example for a complete configuration template.

Test Mode

For testing without a real API key, use the special TEST_KEY value:

export HEVY_API_KEY="TEST_KEY"

This enables mock data mode, which returns realistic test data without making actual API calls. See README_TEST_MODE.md for details.

MCP Client Configuration

Option 1: stdio Mode (Default)

Add the server to your MCP client configuration (e.g., .kiro/settings/mcp.json):

{
  "mcpServers": {
    "hevy": {
      "command": "uvx",
      "args": ["hevy-mcp-server"],
      "env": {
        "HEVY_API_KEY": "your_api_key_here"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "hevy": {
      "command": "python",
      "args": ["-m", "hevy_mcp.server"],
      "cwd": "/path/to/hevy-mcp-server",
      "env": {
        "HEVY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: HTTP/SSE Mode (Server)

Start the HTTP server:

# Start with TEST_KEY (mock data)
python start_http_server.py

# Or with real API key
export HEVY_API_KEY="your_api_key"
python start_http_server.py --port 8000

Then configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "hevy-http": {
      "url": "http://127.0.0.1:8000/sse",
      "transport": "sse"
    }
  }
}

See HTTP_SERVER_GUIDE.md for detailed HTTP server documentation.

Available Tools

The server provides the following MCP tools:

1. get_workout_history

Retrieve paginated workout history.

Parameters:

• page (optional, default: 1): Page number
• page_size (optional, default: 10, max: 10): Number of workouts per page

Example:

Get my last 5 workouts

2. get_workout_details

Get detailed information about a specific workout.

Parameters:

• workout_id (required): The workout ID

Example:

Show me details for workout abc123

3. get_workout_count

Get the total number of workouts on the account.

Example:

How many workouts have I logged?

4. get_exercise_templates

Retrieve paginated list of exercise templates.

Parameters:

• page (optional, default: 1): Page number
• page_size (optional, default: 100, max: 100): Number of templates per page

Example:

Show me available exercises

5. get_exercise_template_details

Get detailed information about a specific exercise template.

Parameters:

• exercise_template_id (required): The exercise template ID

Example:

What muscles does exercise xyz789 work?

6. get_exercise_history

Get exercise history for a specific exercise template.

Parameters:

• exercise_template_id (required): The exercise template ID
• start_date (optional): Start date in ISO 8601 format (e.g., 2025-01-01)
• end_date (optional): End date in ISO 8601 format

Example:

Show my bench press progress over the last month

7. get_routines

Retrieve paginated list of workout routines.

Parameters:

• page (optional, default: 1): Page number
• page_size (optional, default: 10, max: 10): Number of routines per page

Example:

What workout routines do I have?

8. get_routine_details

Get detailed information about a specific routine.

Parameters:

• routine_id (required): The routine ID

Example:

Show me the details of my push day routine

Usage Examples

Once configured in your MCP client, you can interact with your Hevy data using natural language:

• "Show me my workout history from last week"
• "What exercises target the chest?"
• "How has my squat weight progressed over the last 3 months?"
• "What's in my leg day routine?"
• "How many total workouts have I completed?"

Development

Running Tests

pytest

Running the Server Locally

python -m hevy_mcp.server

Error Handling

The server provides clear error messages for common issues:

• Authentication errors: Invalid or missing API key
• Not found errors: Invalid workout/exercise/routine IDs
• Validation errors: Invalid parameters or date formats
• Network errors: Connectivity issues with Hevy API
• Rate limiting: API rate limit exceeded

Requirements

• Python 3.10 or higher
• Valid Hevy API key
• Internet connection to access Hevy API

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Support

For issues related to:

• This MCP server: [Add issue tracker link]
• Hevy API: Contact Hevy support at https://hevyapp.com/support
• MCP Protocol: Visit https://modelcontextprotocol.io

Acknowledgments

Built with FastMCP and powered by the Hevy API.