# Nolio MCP Server

An [MCP](https://modelcontextprotocol.io/) server that gives Claude read-only access to your [Nolio](https://www.nolio.io) training data — planned workouts, completed sessions, metrics, records, and notes.

## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip
- A Nolio API application (client ID + secret) — register at https://www.nolio.io/api/register/

## Quick Start

### 1. Clone and install

```bash
git clone <repo-url> nolio-mcp
cd nolio-mcp
uv sync
```

### 2. Configure client credentials

Create a `.env` file with your Nolio client credentials:

```bash
cp .env.example .env
# Edit .env and fill in NOLIO_CLIENT_ID and NOLIO_CLIENT_SECRET
```

### 3. Authenticate with Nolio

Run the built-in OAuth helper to obtain your access and refresh tokens:

```bash
uv run nolio-auth
```

This opens your browser, you log into Nolio, and all credentials (client ID, client secret, access token, refresh token) are saved to `~/nolio-credentials.json`.

> **Important:** In your Nolio app settings, set the redirect URI to `http://localhost:9876/callback`.

### 4. Add to Claude Code

Since credentials are stored in `~/nolio-credentials.json`, you don't need to pass environment variables:

```bash
claude mcp add nolio -- uv run --directory /path/to/nolio-mcp mcp run src/nolio_mcp/server.py
```

You can also re-authenticate at any time from within Claude Code by running `/mcp` and selecting the `authenticate` command on the `nolio` server, or directly via `/mcp__nolio__authenticate`.

### 4b. Or add to Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nolio": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nolio-mcp", "mcp", "run", "src/nolio_mcp/server.py"]
    }
  }
}
```

No `env` block needed — the server reads credentials from `~/nolio-credentials.json`.

## Available Tools

| Tool | Description |
|------|-------------|
| `get_profile` | Get your Nolio user profile (id, name) |
| `get_planned_workouts` | Retrieve planned workouts from your coach's program |
| `get_workouts` | Retrieve completed/logged workouts |
| `get_workout_streams` | Get time-series data for a workout (HR, pace, power, etc.) |
| `get_notes` | Retrieve notes (injury, availability, illness, rest, goals) |
| `get_metrics` | Get a specific metric (sleep, weight, VO2max, HR, etc.) |
| `get_user_metadata` | Get user metadata (goals, weight history, HR, FTP) |
| `get_records` | Get personal records (power, HR, pace, cadence) |

Most tools support optional `from_date`, `to_date` (YYYY-MM-DD), and `limit` parameters.

## Available Prompts (Commands)

| Prompt | Description |
|--------|-------------|
| `authenticate` | Guides you through the OAuth setup to obtain/refresh Nolio API tokens |

In Claude Code, run `/mcp` → select `nolio` → `authenticate`, or use `/mcp__nolio__authenticate` directly.

## Development

### Testing with the MCP Inspector

```bash
uv run mcp dev src/nolio_mcp/server.py
```

### Running unit tests

```bash
uv run pytest tests/test_client.py
```

### Running integration tests

Integration tests hit the real Nolio API. Set up credentials first:

```bash
cp .test-env.example .test-env
# Fill in .test-env with your Nolio dev credentials
uv run pytest tests/test_integration.py -m integration
```

## API Reference

Full Nolio API documentation: https://github.com/NolioApp/NolioAPI-Documentation/wiki