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