# Gym Coach MCP Server

MCP server that turns any compatible LLM into a personal gym coach with access to your real workout data from [Gym Tracker](https://github.com/nsaporiti/gym-tracker).

Built on the [Model Context Protocol](https://modelcontextprotocol.io/) — works with Claude Desktop, Claude Code, Cursor, Continue, Cline, and any MCP-compatible client.

## What it does

The server connects to your Gym Tracker Supabase database and exposes your training data through 5 tools and 1 resource:

### Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_workout_history` | Recent workouts with exercises, weights, and reps | `limit`, `from_date`, `to_date` |
| `get_exercise_progress` | Progression history for a specific exercise (max weight, volume, trends) | `exercise_name`, `limit` |
| `get_routines` | All routines with exercises, sets, reps, and muscle groups | — |
| `get_training_plan` | Active training plan with progress and completion percentage | — |
| `get_stats_summary` | KPIs: total workouts, frequency, top exercises, PRs | `period_days` |

### Resources

| Resource | Description |
|----------|-------------|
| `gym://exercise-catalog` | Complete exercise catalog with muscle groups and equipment |

## Example prompts

- "How's my bench press progress looking?"
- "Am I training enough leg volume compared to upper body?"
- "Give me a summary of my last month"
- "Am I on track with my training plan?"
- "When was my last PR on squats?"
- "Suggest improvements to my push routine"

## Setup

### 1. Install dependencies

```bash
cd gym-tracker-mcp
npm install
```

### 2. Configure environment

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
GYM_EMAIL=your@email.com
GYM_PASSWORD=your-password
```

> Uses your existing Gym Tracker account credentials. All queries go through Supabase RLS — you can only access your own data.

### 3. Build

```bash
npm run build
```

### 4. Connect to your LLM client

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gym-coach": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gym-tracker-mcp/dist/index.js"]
    }
  }
}
```

#### Claude Code

Add to `.mcp.json` in your project root or `~/.claude.json` globally:

```json
{
  "mcpServers": {
    "gym-coach": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gym-tracker-mcp/dist/index.js"]
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "gym-coach": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gym-tracker-mcp/dist/index.js"]
    }
  }
}
```

#### Continue (VS Code / JetBrains)

Add to `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "gym-coach",
      "command": "node",
      "args": ["/absolute/path/to/gym-tracker-mcp/dist/index.js"]
    }
  ]
}
```

> Replace `/absolute/path/to/` with the actual path to your `gym-tracker-mcp` directory.

## Development

```bash
npm run dev    # Watch mode with tsx (hot reload)
npm run build  # Compile TypeScript to dist/
npm start      # Run compiled server
```

## Architecture

```
gym-tracker-mcp/
├── src/
│   └── index.ts      # MCP server (~450 lines)
├── dist/              # Compiled JS (after npm run build)
├── .env               # Your credentials (not committed)
├── .env.example       # Template
├── package.json
└── tsconfig.json
```

- **Transport:** STDIO (maximum client compatibility)
- **Auth:** `supabase.auth.signInWithPassword()` with user's email/password
- **Security:** Uses anon key + RLS — each user can only access their own data
- **Database:** Reads directly from Gym Tracker's Supabase tables (workouts, routines, exercise_catalog, training_plans)

## Tech stack

- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Supabase JS Client](https://github.com/supabase/supabase-js)
- [Zod](https://github.com/colinhacks/zod) (schema validation)
- TypeScript + Node.js