# Hevy MCP Server

A Model Context Protocol (MCP) server that provides access to workout data from the [Hevy](https://hevyapp.com) 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`:

```bash
uvx hevy-mcp-server
```

### Using pip

```bash
pip install hevy-mcp-server
```

### Development Installation

Clone the repository and install in development mode:

```bash
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](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:

```bash
# 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:

```bash
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](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`):

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

For local development:

```json
{
  "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:

```bash
# 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:

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

See [HTTP_SERVER_GUIDE.md](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

```bash
pytest
```

### Running the Server Locally

```bash
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](https://github.com/jlowin/fastmcp) and powered by the [Hevy API](https://hevyapp.com).