eufy-cam-mcp
This server gives an AI agent view-only, local access to four allowlisted Eufy cameras via MediaMTX.
List known cameras with their ready state and tracks.
Get one camera’s ready state, tracks, received bytes, and inbound frame errors.
Capture a single JPEG snapshot from a camera’s local RTSP stream and return its path.
Report recording segment count, total bytes, oldest/newest filenames, and a fixed retention note.
List the newest motion clips for a camera, with a capped limit and count/bytes totals.
Extract one JPEG frame at a specified time from a named clip.
Enforce camera-name allowlisting and reject path traversal, cross-camera clips, and invalid timestamps.
Does not provide PTZ, talkback, cloud API access, recording, or retention management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@eufy-cam-mcp show me which eufy cameras are online and grab a snapshot from eufy_cam1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
eufy-camera-mcp
A Python FastMCP server that gives an AI agent view-only access to an allowlisted set of local Eufy cameras through MediaMTX: live status, a single JPEG snapshot, and recorded motion clips. It has no PTZ, no talkback, and no cloud API.
Why it exists
An agent that can see a camera should not be able to reach cameras it was not given, call out to the internet, or move the camera. This server keeps the surface small: four known camera names, localhost MediaMTX only, and one frame at a time.
Related MCP server: @mgcrea/mcp-unifi-protect
Tools
The server registers six tools (src/eufy_cam_mcp/server.py).
Tool | What it returns |
| Each known camera with its ready state and tracks from MediaMTX |
| Ready state, tracks, received bytes, and inbound frames in error for one camera |
| Path to one JPEG frame grabbed with |
|
|
| Paths of the newest |
| Path to one JPEG frame at |
Every per-camera tool rejects names outside the allowlist, including path traversal attempts such as ../../outside, before any MediaMTX call or ffmpeg process. clip_frame also rejects clip names that are not a bare *.mp4 file name, clips whose name does not start with <name>_ (a camera cannot read another camera's recording), and a negative or non-finite t. It returns clip not found for a name that does not exist in the recordings folder, and ffmpeg extraction failed when t is past the end of the clip.
snapshot_camera and clip_frame write JPEGs to the snapshot folder. Nothing prunes them. On a successful capture, snapshot_camera unlinks any existing <name>_latest.jpg file or symlink before creating the new symlink. Captures of the same camera within one UTC second reuse the timestamped JPEG path, and ffmpeg -y can overwrite that JPEG. clip_frame removes its own earlier output before a re-run writes it again.
clip_frame names its file <name>_<clip stem>_t<t>.jpg, where <t> is t formatted with Python :g (5.0 gives t5, 5.5 gives t5.5). recordings_info sorts by file name, so with several cameras its first and last entries are alphabetical, not oldest and newest in time.
Requirements
Python 3.12 or newer and uv
ffmpegonPATHA MediaMTX instance on the same host with its API enabled, publishing your cameras as
eufy_cam1toeufy_cam4A recorder that writes
<name>_*.mp4segments into the recordings folder, if you want the recording tools (not part of this repo)
Install and run
git clone https://github.com/thefiredev-cloud/eufy-camera-mcp.git
cd eufy-camera-mcp
uv sync --frozen
uv run eufy-cam-mcpThis starts the MCP server on stdio. Register it with your MCP client as a stdio command, for example:
{
"mcpServers": {
"eufy-cam": {
"command": "uv",
"args": ["--directory", "/path/to/eufy-camera-mcp", "run", "eufy-cam-mcp"]
}
}
}Configuration
Settings are constants at the top of src/eufy_cam_mcp/server.py:
Constant | Default |
|
|
|
|
|
|
|
|
|
|
The ~/meshvault/... folders are the defaults used on the author's machines. Edit the constants to match your layout; there are no environment variable overrides yet.
Check it without cameras
The boundary check calls camera_status and snapshot_camera with four bad camera names and confirms that no MediaMTX call, network connection, ffmpeg process, or snapshot folder was created. The pytest suite has nine cases: unknown camera rejection, newest-first clip listing, clip_frame rejection of unknown cameras, missing clips, path escapes, another camera's clip and negative t values. The implementation also rejects non-finite t values, but the suite does not test them. One clip_frame test uses a synthetic video and is skipped when ffmpeg is not installed.
uv run ruff check .
uv run python scripts/check-camera-boundaries.py
uv run pytest -vCI runs Ruff, the boundary check, and the test suite on pushes and pull requests to main.
Scope
In scope: allowlisted names, MediaMTX ready state from /v3/paths/list, one-frame JPEG capture, and listing and sampling local motion clips.
Out of scope: PTZ, talkback, Eufy cloud APIs, recording, and retention. Recording belongs to a separate recorder service; this server only reads files already on disk.
Status
Early, version 0.1.0. The tests and the boundary check cover input rejection and clip listing, and one test runs real ffmpeg on a generated clip through clip_frame. No test talks to MediaMTX, captures from RTSP, or uses a camera. If MediaMTX is unreachable, list_cameras and camera_status raise an error instead of returning a not-ready state. If MediaMTX is reachable but does not list a known camera, list_cameras reports it as not ready with no tracks, and camera_status returns ready: false with the error not found in MediaMTX. ffmpeg calls are limited to 60 seconds, and a timeout also raises. Not published to PyPI and not deployed as a hosted service.
Architecture
A view-only MCP server that lets an AI agent see four allowlisted local Eufy cameras through MediaMTX.
flowchart LR
agent(["AI agent<br/>MCP client"]):::actor
server["MCP server<br/>6 view-only tools"]:::app
mtx{{"MediaMTX<br/>localhost only"}}:::ext
ffmpeg["ffmpeg<br/>one frame<br/>60 s cap"]:::job
snaps[("Snapshots<br/>JPEG files")]:::store
recs[("Recordings<br/>mp4, read-only")]:::store
agent -->|"asks"| server
server -->|"status"| mtx
server -->|"grab"| ffmpeg
ffmpeg -->|"writes"| snaps
recs -->|"clips"| server
classDef actor fill:#fde68a,stroke:#b45309,color:#111827
classDef app fill:#bfdbfe,stroke:#1d4ed8,color:#0b1220
classDef ext fill:#e5e7eb,stroke:#4b5563,color:#0b1220,stroke-dasharray:4 3
classDef job fill:#fbcfe8,stroke:#be185d,color:#0b1220
classDef store fill:#bbf7d0,stroke:#15803d,color:#0b1220Full architecture · Hi-res: SVG · PNG 3x · dark PNG · Explorable (Archify) · Graphify report
License
All rights reserved. See LICENSE. Licensing questions and contact: tanner@kodros.ai.
Available Tools
6 toolscamera_statusC
Ready state, tracks, and error counters for one camera.
Inputs: name. Returns: object
clip_frameB
Extract one JPEG frame at t seconds into a motion clip. Returns the file path.
Inputs: t, clip, name. Returns: object
list_camerasB
List known Eufy cameras with live ready state from MediaMTX.
Inputs: no named parameters. Returns: result
motion_clipsB
Newest motion-event recordings for one camera (newest first, capped).
Inputs: name, limit. Returns: object
recordings_infoB
Segment count, disk use, and oldest/newest recording (retention visibility).
Inputs: no named parameters. Returns: object
snapshot_cameraC
Capture a single JPEG frame from a camera. Returns the file path.
Inputs: name. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools mostly target distinct resources: list all cameras, get one camera status, snapshot live, get recordings overview, list motion clips, and extract a clip frame. However, snapshot_camera and clip_frame both return a JPEG file path, and camera_status partially overlaps list_cameras' ready state, so minor confusion is possible.
All names use snake_case, but the patterns are mixed: verbs (list_cameras, snapshot_camera, clip_frame) alternate with noun phrases (camera_status, recordings_info, motion_clips). Still readable, but not a consistent verb_noun convention.
Six tools is well within the ideal 3–15 range for a camera monitoring server, and each tool appears to serve a distinct purpose.
Core monitoring and frame-extraction workflows are covered, but there is no direct tool to retrieve or download a full motion clip (only frame extraction), and no camera control or configuration operations. These are minor gaps for the apparent monitoring-focused purpose.
Maintenance
Related MCP Connectors
Give the physical world an API: cameras become typed endpoints your agent can read and act on.
Watch cameras and video with AI vision and get alerts in Slack, Discord, Telegram or a webhook.
Ask your security cameras anything and set up alert rules in a sentence. Built into Agent DVR.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Related MCP Servers
- FlicenseAqualityBmaintenanceEnables AI assistants to interact with Frigate NVR security camera systems, supporting camera management, event detection, snapshots, recordings, and system stats via natural language.714-
- AlicenseAqualityBmaintenanceEnables interacting with a self-hosted UniFi Protect console through natural language, covering cameras, recorded events, smart detections, snapshots, footage export, and connected devices, with optional write access.2248 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query and interact with Extra Low Voltage security hardware such as Hikvision and Dahua cameras and NVRs through typed, read-only-by-default MCP tools for device info, channel enumeration, and JPEG snapshot capture. Translates proprietary ISAPI and CGI protocols into safe, auditable calls that any MCP client can use over stdio.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants and MCP clients to inspect camera streams, probe video/audio codecs, capture live JPEG snapshots, generate playback URLs, discover camera integrations, and manage streams dynamically with strict credential redaction.121MIT