blueiris-mcp

An MCP server for Blue Iris, 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).

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`)

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

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

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

Tests are fully mocked (via respx) — no live Blue Iris instance needed.

License

MIT