Frigate MCP Server

A Model Context Protocol (MCP) server for Frigate NVR, enabling AI assistants to interact with your Frigate security camera system.

![Python Version](https://www.python.org/downloads/) ![License](LICENSE)

🌟 Features

Camera Management: List and monitor all configured cameras
Event Detection: Query detection events with filtering by camera, object type, and time
Live Snapshots: Get current or historical camera snapshots
Recordings: Access recording summaries and segments
System Stats: Monitor Frigate performance, detector speed, and camera FPS
Configuration: Retrieve complete Frigate configuration

📋 Prerequisites

Python 3.10 or higher
A running Frigate NVR instance
Access to the Frigate HTTP API

🚀 Installation

1. Clone the repository

git clone https://github.com/yourusername/frigate-mcp.git
cd frigate-mcp

2. Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

pip install -e .

4. Configure environment

Create a .env file in the project root:

# Required: URL of your Frigate instance
FRIGATE_FRIGATE_URL=http://localhost:5000

# Optional: API key if authentication is required
# FRIGATE_API_KEY=your_secret_key_here

# Optional: HTTP timeout in seconds (default: 30)
# FRIGATE_TIMEOUT=30

🔧 Configuration

The server uses environment variables for configuration. You can set them in:

.env file (recommended for development)
Environment variables (recommended for production)

Configuration Options

| Variable | Description | Default | Required | | --------------------- | ------------------------------ | ----------------------- | -------- | | FRIGATE_FRIGATE_URL | Base URL of Frigate instance | http://localhost:5000 | No | | FRIGATE_API_KEY | API key for authentication | None | No | | FRIGATE_TIMEOUT | HTTP request timeout (seconds) | 30 | No | | FRIGATE_SERVER_HOST | Server host for SSE/HTTP modes | 0.0.0.0 | No | | FRIGATE_SERVER_PORT | Server port for SSE/HTTP modes | 8000 | No |

Example Configurations

Local Frigate instance: ``bash FRIGATE_FRIGATE_URL=http://localhost:5000 ``

Remote Frigate with authentication: ``bash FRIGATE_FRIGATE_URL=http://192.168.1.100:5000 FRIGATE_API_KEY=your_secret_key FRIGATE_TIMEOUT=60 ``

🎯 Usage

The server supports three operational modes:

1. STDIO Mode (Default)

For direct integration with MCP clients like Claude Desktop:

python -m frigate_mcp.server
# or
frigate-mcp

2. SSE Mode (Server-Sent Events)

For web-based clients with real-time updates:

frigate-mcp-sse

The server will start at http://localhost:8000/sse (configurable via environment variables).

Features:

Real-time event streaming
WebSocket-like experience over HTTP
Easy to debug in browser dev tools
Compatible with web applications

3. HTTP Mode (REST API)

For production deployments and API access:

STDIO Mode (for MCP clients):

python -m frigate_mcp.server

SSE Mode (for web clients):

frigate-mcp-sse

HTTP Mode (for REST API):

frigate-mcp-http

Integrating with MCP Clients

Claude Desktop (STDIO Mode)

Testing the Connection

Run the included test script to verify your Frigate connection:

python test_connection.py

Expected output: ``` ============================================================ Frigate MCP Server - Connection Test ============================================================

🔧 Frigate Configuration: URL: http://localhost:5000 API URL: http://localhost:5000/api Timeout: 30s

📹 Testing /api/config (cameras)... ✅ Found 1 camera(s)

front_door: enabled

📊 Testing /api/stats... ✅ Frigate version: 0.16.3 ✅ Detectors: ['coral'] ✅ Active cameras: ['front_door'] ... ```

Running the MCP Server

Start the server in stdio mode (for MCP clients):

python -m frigate_mcp.server

Claude Desktop (STDIO Mode)

Add to your MCP client configuration (e.g., Claude Desktop config.json):

{
  "mcpServers": {
    "frigate": {
      "command": "/path/to/frigate-mcp/.venv/bin/python",
      "args": ["-m", "frigate_mcp.server"],
      "env": {
        "FRIGATE_FRIGATE_URL": "http://localhost:5000"
      }
    }
  }
}

Web Clients (SSE Mode)

Connect to the SSE endpoint for real-time updates:

const eventSource = new EventSource('http://localhost:8000/sse');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

REST API (HTTP Mode)

Make standard HTTP requests:

# Get cameras
curl http://localhost:8000/tools/get_cameras

# Get events
curl http://localhost:8000/tools/get_events?limit=5

# Get stats
curl http://localhost:8000/tools/get_stats

Or use any HTTP client:

import requests

response = requests.post(
    'http://localhost:8000/tools/get_events',
    json={'camera': 'front_door', 'limit': 10}
)
print(response.json())   "frigate": {
      "command": "/path/to/frigate-mcp/.venv/bin/python",
      "args": ["-m", "frigate_mcp.server"],
      "env": {
        "FRIGATE_FRIGATE_URL": "http://localhost:5000"
      }
    }
  }
}

🛠️ Available Tools

The server provides 7 MCP tools for interacting with Frigate:

1. `get_cameras()`

List all configured cameras with their status and properties.

Returns: ``json [ { "name": "front_door", "enabled": true, "width": 1920, "height": 1080, "fps": 5 } ] ``

2. `get_events(camera, label, limit)`

Get recent detection events with optional filtering.

Parameters:

camera (optional): Filter by camera name
label (optional): Filter by object type (person, car, dog, etc.)
limit (default: 10): Maximum events to return (1-100)

Example: ``python get_events(camera="front_door", label="person", limit=5) ``

Returns: ``json [ { "id": "1234567890.123456-abcdef", "camera": "front_door", "label": "person", "start_time": 1704067200.5, "end_time": 1704067205.8, "has_clip": true, "has_snapshot": true, "zones": ["entrance"], "thumbnail": "http://localhost:5000/api/events/1234.../thumbnail.jpg" } ] ``

3. `get_stats()`

Get Frigate system statistics and performance metrics.

Returns: ``json { "service": { "uptime": 86400, "version": "0.16.3", "storage": {...} }, "detectors": { "coral": { "inference_speed": 8.5, "detection_start": 1704067200.0 } }, "cameras": { "front_door": { "camera_fps": 5.0, "process_fps": 5.0, "detection_fps": 1.2 } } } ``

4. `get_event_details(event_id)`

Get comprehensive details about a specific event.

Parameters:

event_id: Unique event identifier

Returns: ``json { "id": "1234567890.123456-abcdef", "camera": "front_door", "label": "person", "start_time": 1704067200.5, "end_time": 1704067205.8, "duration": 5.3, "score": 0.87, "zones": ["entrance"], "has_clip": true, "has_snapshot": true, "media": { "thumbnail": "http://localhost:5000/api/events/.../thumbnail.jpg", "snapshot": "http://localhost:5000/api/events/.../snapshot.jpg", "clip": "http://localhost:5000/api/events/.../clip.mp4" } } ``

5. `get_snapshot(camera, timestamp)`

Get a snapshot URL from a specific camera.

Parameters:

camera: Camera name
timestamp (optional): Unix timestamp for historical snapshot

Returns: ``json { "camera": "front_door", "timestamp": "latest", "url": "http://localhost:5000/api/front_door/latest.jpg", "description": "Snapshot from front_door (latest)" } ``

6. `get_recordings(camera, date)`

Get recording information for a specific camera and date.

Parameters:

camera: Camera name
date (optional): Date in YYYY-MM-DD format (defaults to today)

Returns: ``json { "camera": "front_door", "date": "2024-01-01", "recordings_count": 24, "total_duration": 86400, "recordings": [ { "day": "2024-01-01", "hour": "10", "duration": 3600, "events": 5 } ] } ``

7. `get_config()`

Get Frigate configuration summary.

Returns: ``json { "cameras": ["front_door", "backyard", "garage"], "detectors": ["coral"], "mqtt": { "enabled": true, "host": "localhost" }, "model": "path/to/model.tflite", "version": "0.16.3" } ``

🏗️ Project Structure

frigate-mcp/
├── src/
│   └── frigate_mcp/
│       ├── __init__.py       # Package metadata
│       ├── config.py         # Configuration management
│       └── server.py         # MCP server & tools
├── test_connection.py        # Connection test script
├── pyproject.toml           # Project dependencies
├── .env                     # Environment variables (not in git)
└── README.md                # This file

---

Made with ❤️ for the Frigate and MCP communities

Frigate MCP Server