ring-recap-mcp

Turn your Ring cameras into a searchable, time-coded daily log that AI agents can read.

Every night, on your own Mac, ring-recap-mcp:

1. pulls every Ring event clip from one location for the previous day,

2. transcribes the audio with whisper.cpp,

3. describes sampled frames with a vision model (Grok, or a local model through Ollama),

4. writes per-camera and whole-site recaps, and

5. serves all of it over MCP.

Your agent can then ask "what happened at the shop yesterday?", and follow up with "show me the back door around 2:30 PM".

Status: early. Ring sign-in, the event pull and the ledger work and are tested against a live 8 camera location (Phases 0 and 1). Transcription, descriptions, recaps, 7 day footage retention and the time-frame tools are specified in docs/ROADMAP.md and being built.

Why local

• Video and audio are processed on your Mac. Only sampled JPEG frames go to the vision model you choose, and with Ollama nothing leaves the machine at all.

• Your Ring token and API keys live in the macOS Keychain, never in files.

• Footage is kept for a rolling week (configurable). Text, JSON and thumbnails are kept longer.

Related MCP server: ailoud

How it works

flowchart LR
  Ring[(Ring cloud)] -->|event clips| Sync[nightly sync<br/>launchd]
  Sync --> Footage[(footage<br/>7 days)]
  Footage --> Whisper[whisper.cpp<br/>timed transcript]
  Footage --> Frames[ffmpeg<br/>timed frames]
  Frames -->|JPEGs only| Vision[vision model]
  Whisper --> Ledger[(SQLite + FTS)]
  Vision --> Ledger
  Ledger --> Recaps[daily recaps]
  Ledger --> MCP[MCP server<br/>stdio + HTTP]
  Footage --> MCP
  MCP --> Agent[your agent]

Requirements

• A Mac with Apple Silicon that stays on (a Mac mini is ideal), macOS 14 or newer

• Homebrew and Node 22 or 24

• About 2 GB for tools and the whisper model, plus room for a week of footage (anywhere from a few GB to about 85 GB for a busy 8 camera site)

• A Ring account with video recording, and end-to-end encryption turned off for the cameras you want recapped

• For descriptions: an xAI API key, or Ollama with a vision model

Quick start

git clone https://github.com/headlessfounder/ring-recap-mcp.git ~/ring-recap-mcp
cd ~/ring-recap-mcp
scripts/install.sh deps && scripts/install.sh model && scripts/install.sh check
scripts/install.sh build && npm test
scripts/install.sh config          # then edit ~/.config/ring-recap/config.json
scripts/auth.sh                    # Ring sign-in (email, password, 2FA), token goes to Keychain
node dist/index.js --run list_cameras
node dist/index.js --run sync_day --stage download    # yesterday's clips

Running it unattended on a headless Mac covers sleep, auto-login, Keychain and launchd. That setup has its own guide: docs/INSTALL_HEADLESS_MAC.md. It is written so an AI agent can follow it step by step.

Configuration

~/.config/ring-recap/config.json (or $RING_RECAP_CONFIG). Every key is optional.

Secrets are not config. They live in the Keychain under service ring-recap:

• account ring-refresh-token, written by scripts/auth.sh

• account xai-api-key

CLI

node dist/index.js --doctor                                   # what is installed and found
node dist/index.js --run list_cameras
node dist/index.js --run sync_day --date 2026-11-07 --stage download
node dist/index.js --run sync_day --catch-up                  # what the nightly job runs
node dist/index.js --run health

Exit codes: 0 ok, 1 error, 2 Ring auth expired or no token, 3 low disk, 4 another sync is running.

MCP

stdio (Claude Desktop, Claude Code and other local clients):

{ "mcpServers": { "ring-recap": { "command": "node", "args": ["/Users/you/ring-recap-mcp/dist/index.js"] } } }

Streamable HTTP: http://127.0.0.1:8787/mcp. Start it with node dist/index.js --http, or keep it running with scripts/install.sh launchd server. It is stateless, POST only, bound to localhost, and rejects foreign Host and Origin headers. For an agent on another machine, use an SSH tunnel (see the install guide).

Roadmap

docs/ROADMAP.md has the design and acceptance checks for each phase:

• time-coded transcripts and "moments"

• camera areas

• 7 day footage retention

• the drill-down tools

• the cost budget for vision models

Contributors and coding agents should start with AGENTS.md.

Implementation notes

• ring-client-api 14.3.0 is pinned, and every call goes through src/ring/client.ts (tested 2026-11-08). The library retries network errors forever, so each call there has a hard 90 s timeout.

• Location names can carry trailing spaces. Matching is trimmed and case-insensitive.

• videoSearch returns at most 20 rows, newest first, and ignores order=asc. Any full page is split (4 hour windows, then halves, down to 1 minute) until every window comes back under the cap. A busy day needed 69 splits.

• Events whose video 404s on every URL are recorded as recording_unavailable. Only 401/403 on every download from a camera counts toward the end-to-end encryption warning.

• Downloaded MP4s run 1 to 6 s longer than Ring's duration field, so wall-clock times can be a few seconds off. Instead of calibrating, the time-frame tools pad every window by timePaddingSeconds (default 10) on both sides (roadmap section 4).

• security -i truncates input lines over about 4 KB, so Keychain writes use stdin for short values and argv for long ones, and always read the value back.

• Clips with hq_url: null that are still processing stay queued for the next run. A failed clip is retried once on the next run, then left as failed.

Privacy and legal

You are responsible for how you use this.

• Recording and transcribing conversations is regulated in many places, and some require the consent of everyone recorded.

• Face recognition (optional, off by default) is regulated as biometric data in some places.

• Post notice where required, keep the vault private (it is created chmod 700), and turn on FileVault.

This project uses an unofficial, reverse-engineered Ring API through ring-client-api, and it can break when Ring changes things. It is not affiliated with, endorsed by or supported by Ring or Amazon. Use it only with cameras and accounts you own or administer.

License

MIT