Frigate MCP Server
# Frigate MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Frigate NVR](https://frigate.video/), enabling AI assistants to interact with your Frigate security camera system.
[](https://www.python.org/downloads/)
[](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](https://frigate.video/) instance
- Access to the Frigate HTTP API
## š Installation
### 1. Clone the repository
```bash
git clone https://github.com/yourusername/frigate-mcp.git
cd frigate-mcp
```
### 2. Create a virtual environment
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
### 3. Install dependencies
```bash
pip install -e .
```
### 4. Configure environment
Create a `.env` file in the project root:
```bash
# 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:
1. **`.env` file** (recommended for development)
2. **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:
```bash
python -m frigate_mcp.server
# or
frigate-mcp
```
### 2. SSE Mode (Server-Sent Events)
For web-based clients with real-time updates:
```bash
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):
```bash
python -m frigate_mcp.server
```
**SSE Mode** (for web clients):
```bash
frigate-mcp-sse
```
**HTTP Mode** (for REST API):
```bash
frigate-mcp-http
```
### Integrating with MCP Clients
#### Claude Desktop (STDIO Mode)
### Testing the Connection
Run the included test script to verify your Frigate connection:
```bash
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):
```bash
python -m frigate_mcp.server
```
#### Claude Desktop (STDIO Mode)
Add to your MCP client configuration (e.g., Claude Desktop `config.json`):
```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:
```javascript
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:
```bash
# 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:
```python
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
TDQS
Scored across 7 tools
Each tool targets a distinct resource and action: camera listing, event listing, event detail, stats, snapshot, recordings, and config. get_events vs get_event_details might superficially overlap, but list-vs-detail is a clear and standard distinction.
All seven tools follow a strict get_<resource> snake_case pattern. No mixed conventions or vague verbs.
Seven tools is well-scoped for a read-oriented Frigate monitoring server. Each tool covers a distinct query surface without padding.
Core read workflows are covered: cameras, events, event details, snapshots, recordings, stats, and config. Write/administrative operations (event deletion, retention updates, restarts) are absent, but likely out of scope for a read-focused monitoring server.