# blueiris-mcp

An [MCP](https://modelcontextprotocol.io) server for [Blue Iris](https://blueirissoftware.com/), the Windows NVR/camera-management software. Lets an LLM check camera health, pull live or historical snapshots, search the clip/alert archive, and drive PTZ cameras — all through Blue Iris's existing JSON API, no extra software on the Blue Iris box required.

Blue Iris's JSON API is undocumented enough that its session-handshake auth scheme (a custom two-step MD5 challenge, not a bearer token or HTTP digest) has to be reverse-engineered by reading network traffic. This package does that once so you don't have to.

## Why

Blue Iris already has a web UI and a JSON API, but neither is something an LLM agent can use directly. This wraps the API as MCP tools so an agent can answer questions like:

- "Is the front door camera actually seeing anything right now, or is it stuck on the no-signal placeholder?"
- "Show me what the driveway camera saw at 6pm yesterday."
- "Who showed up at the front door today?" (Blue Iris's own AI recognition results are in the alert log's `memo` field, e.g. `"John:74%"`)
- "Pan the workshop camera left for a second and grab a frame."

## Tools

| Tool | Description |
|---|---|
| `list_cameras` | Configured cameras with live health: `is_no_signal` (the actual "no video" placeholder state, distinct from `is_online`), `fps`, `error`, `ptz_capable`. |
| `get_snapshot` | Live or historical JPEG frame (`pos_ms` = Unix epoch ms for historical). Returned as image content, not a file path. |
| `list_clips` | Recorded segments for a camera, newest first, across Blue Iris's full retention window for that camera. |
| `list_alerts` | Motion/AI alerts for a camera, newest first, including Blue Iris's own recognition `memo` when present. |
| `ptz` | Directional nudge, home, zoom in/out, stop, or jump to a saved preset. |

## Setup

Requires a Blue Iris account with JSON API access (the same username/password as the web UI login).

```bash
pip install blueiris-mcp
# or: uvx blueiris-mcp
```

Configure via environment variables:

| Variable | Required | Default |
|---|---|---|
| `BI_URL` | no | `http://localhost:81` |
| `BI_USER` | yes | — |
| `BI_PASSWORD` | yes | — |

### Claude Code / Claude Desktop (`~/.claude.json` or `claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "blueiris": {
      "command": "uvx",
      "args": ["blueiris-mcp"],
      "env": {
        "BI_URL": "http://192.168.1.50:81",
        "BI_USER": "your-username",
        "BI_PASSWORD": "your-password"
      }
    }
  }
}
```

### Hermes (`~/.hermes/config.yaml`)

Hermes' `mcp_servers` config supports the same stdio transport:

```yaml
mcp_servers:
  blueiris:
    command: uvx
    args: ["blueiris-mcp"]
    env:
      BI_URL: "http://192.168.1.50:81"
      BI_USER: "your-username"
      BI_PASSWORD: "your-password"
```

## Notes on the Blue Iris API

- Auth: `POST /json {"cmd":"login"}` returns a `session` token. Then `POST /json {"cmd":"login","session":<id>,"response":<hash>}` where `hash = md5(f"{user}:{session}:{password}")` — a single MD5 pass, no realm string. This client re-authenticates on every call rather than caching a session, since call volume through an MCP tool is inherently low.
- `list_clips`/`list_alerts` (Blue Iris's `cliplist`/`alertlist` commands) have no date-range parameters — they return everything currently retained on disk for that camera. Retention is whatever Blue Iris is configured to keep (commonly a few days to a couple of weeks, storage-dependent).
- If your setup has another process also driving a camera's PTZ (e.g. an automated monitoring script), avoid sending PTZ commands to that camera at the same time from here — Blue Iris does not arbitrate between simultaneous PTZ sources, and the result is erratic movement.

## Development

```bash
uv venv && uv pip install -e ".[dev]"
uv run pytest
```

Tests are fully mocked (via [respx](https://github.com/lundberg/respx)) — no live Blue Iris instance needed.

## License

MIT