# MCP Nightscout by [B77.ai](https://b77.ai)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects AI assistants to [Nightscout](http://www.nightscout.info/) — the open-source CGM remote monitoring platform for Type 1 Diabetes management.

Built with [FastMCP](https://github.com/jlowin/fastmcp), this server exposes Nightscout data as MCP tools, enabling AI assistants like Claude to read glucose data, analyze patterns, log treatments, and more.

## Features

### Glucose Monitoring

- **get_current_glucose** — latest CGM reading with value, trend arrow, and device info
- **get_recent_glucose** — recent readings (default: last 3 hours)
- **get_glucose_by_date_range** — readings for a specific date range

### Analytics

- **calculate_time_in_range** — TIR stats with breakdown (in range, below, above, very low, very high), estimated A1C, and coefficient of variation
- **get_daily_glucose_stats** — daily stats with hourly averages
- **analyze_glucose_patterns** — multi-day pattern analysis to identify recurring highs/lows by time of day

### Treatments

- **get_recent_treatments** — recent insulin boluses, carb entries, temp basals, notes
- **get_treatments_by_date** — treatments for a specific date range
- **log_treatment** — log a new treatment (bolus, carbs, exercise, note, etc.)
- **remove_treatment** — delete a treatment by ID

### Device & Profile

- **get_insulin_on_board** — current IOB from loop/pump device status
- **get_latest_device_status** — pump status, loop decisions, CGM status
- **server_status** — Nightscout server version, plugins, thresholds, units
- **get_current_profile** — basal rates, ISF, IC ratios, target BG, DIA
- **update_nightscout_profile** — update profile settings

## Quick Start

### 1. Clone and configure

```bash
git clone https://github.com/easyweek/mcp-nightscout.git
cd mcp-nightscout
cp .env.example .env
```

Edit `.env` with your Nightscout instance details:

```env
NIGHTSCOUT_URL=https://your-nightscout.example.com
NIGHTSCOUT_TOKEN=your-readable-token
MCP_AUTH_TOKEN=your-secret-mcp-token
```

### 2. Run with Docker

```bash
docker compose up --build
```

The server starts on `http://localhost:8000`.

### 3. Connect to Claude

#### Claude Code (CLI)

Add to your MCP settings:

```json
{
  "mcpServers": {
    "nightscout": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-mcp-token"
      }
    }
  }
}
```

#### Claude.ai (remote)

When deployed to a public URL, connect using the token-in-path format:

```
https://your-server.example.com/mcp/your-secret-mcp-token
```

## Authentication

The server supports two auth modes for MCP clients:

| Method        | Format                          | Use case             |
| ------------- | ------------------------------- | -------------------- |
| Bearer header | `Authorization: Bearer <token>` | Claude Code CLI      |
| Token in path | `POST /mcp/<token>`             | Claude.ai connectors |

The `/health` endpoint is always open (no auth required).

Set `MCP_AUTH_TOKEN` to enable authentication. If unset, the server runs without auth (suitable for local development only).

### Nightscout Authentication

Connect to your Nightscout instance using **either**:

- **API secret** (`NIGHTSCOUT_API_SECRET`) — SHA1 hash of your plaintext secret:
  ```bash
  echo -n "your-secret" | shasum -a 1 | awk '{print $1}'
  ```
- **Readable token** (`NIGHTSCOUT_TOKEN`) — created in Nightscout Admin Tools

## Development

### Run locally (without Docker)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn src.server:app --host 0.0.0.0 --port 8000 --log-config src/log_config.yaml
```

### Run tests

```bash
pip install pytest pytest-asyncio
pytest tests/
```

### Project structure

```
src/
  server.py             # MCP tools, auth middleware, health endpoint
  nightscout_client.py  # HTTP client for Nightscout REST API v1
  log_filter.py         # Filters /health from access logs
  log_config.yaml       # JSON logging configuration
tests/
  test_auth.py          # Auth middleware tests
```

### Adding a new tool

1. Add the API call to `src/nightscout_client.py` if needed
2. Add a `@mcp.tool()` function in `src/server.py` with a clear docstring
3. Test with `docker compose up --build`

## Environment Variables

| Variable                | Required | Default | Description                  |
| ----------------------- | -------- | ------- | ---------------------------- |
| `NIGHTSCOUT_URL`        | Yes      | —       | Nightscout instance base URL |
| `NIGHTSCOUT_API_SECRET` | No\*     | —       | API secret (SHA1 hash)       |
| `NIGHTSCOUT_TOKEN`      | No\*     | —       | Readable token               |
| `NIGHTSCOUT_TIMEOUT`    | No       | `30`    | Request timeout in seconds   |
| `MCP_AUTH_TOKEN`        | No       | —       | MCP server auth token        |

\* One of `NIGHTSCOUT_API_SECRET` or `NIGHTSCOUT_TOKEN` is required.

## License

[MIT](LICENSE) — Copyright (c) – 2026 B77.ai (EasyWeek GmbH)