retrace-mcp

Read-only MCP server over the local Retrace screen-history database, so Claude can search what has been on your screen.

Six tools. No write path anywhere in the code — not a disabled one, none.

Read SECURITY.md before connecting this to anything. It exposes the OCR'd text of everything you have had on screen, and the prompt-injection section describes a risk the deny-list does not cover.

search_text("quarterly planning")
  2026-02-11T09:00:00-08:00  Google Chrome   Quarterly planning - Docs
    ...Quarterly <mark>planning</mark> document. Revenue targets for the...

Requirements

macOS with Retrace installed, uv, and the claude CLI. Python ≥3.11 (uv provisions its own, so a system Anaconda will not be picked up). Built and verified against Retrace 0.8.7.

Install

git clone https://github.com/calvingunther66/retracemcpclaude.git
cd retracemcpclaude
bash install.sh

Installs systemwide (claude mcp add --scope user) — available in every Claude session on the machine. The installer creates your config from the example, verifies your database schema matches what the server expects, runs the test suite, and only then registers the server.

Remove it at any time:

claude mcp remove retrace

Tools

Every tool takes an optional limit (default 20, maximum 100). Timestamps cross the boundary as ISO 8601 local time in both directions — pass 2026-02-11 or 2026-02-11T09:30:00, get back 2026-02-11T09:30:00-08:00. Raw epoch milliseconds never leak out. Every tool applies the deny-list inside its SQL.

Tool	Returns
search_text(query, start?, end?, bundle_ids?, limit?)	Full-text search over screen OCR. One hit per frame with a <mark>-highlighted snippet, app, window title, URL, and the video id / frame index.
list_segments(start?, end?, bundle_id?, limit?)	Capture segments — one contiguous stretch in one app window — with start, end and duration.
get_frame(frame_id, limit?)	One frame with its OCR text boxes and parent segment.
app_usage(start, end, limit?)	Time per app across a window, ordered descending, with display names.
list_tags(limit?) / segments_by_tag(tag, limit?)	Retrace's segment tags.

search_text accepts FTS5 syntax: invoice, "exact phrase", budget NEAR/5 forecast, sched*.

OCR box geometry is normalised 0.0–1.0, not pixels. Multiply by the video's width and height for pixel coordinates.

processing_queue is never queried — it is the hot live OCR queue.

Configuration

retrace_mcp.toml in the repo root, created from retrace_mcp.example.toml on install. Changes take effect on restart.

[database]
path = "~/Library/Application Support/Retrace/retrace.db"

[privacy]
exclude_bundles         = ["com.apple.Terminal", "com.1password.1password", ...]
exclude_url_patterns    = ["chase.com", "vanguard.com", ...]
exclude_window_patterns = ["1Password", "Online Banking", ...]
exclude_hidden_segments = true
skip_redacted           = true

Key	Effect
exclude_bundles	App bundle IDs hidden from every tool.
exclude_url_patterns	Substrings matched against the segment's browser URL.
exclude_window_patterns	Substrings matched against the window title.
exclude_hidden_segments	Honour Retrace's own hidden tag.
skip_redacted	Drop rows whose snippet is rtx1. redaction ciphertext.

Why URL and window patterns exist. Excluding applications is not enough on its own. Banking, webmail and health portals run inside a browser, under an allowed bundle ID — a bundle-only deny-list leaves every one of those pages fully searchable. The URL and window lists are what actually close that gap, and they are the ones worth maintaining.

Filters are applied inside each query, never as a post-filter. Post-filtering leaks through LIMIT: an excluded row would consume a result slot, and its text would have been read into the process regardless. % and _ in patterns are escaped and matched literally.

Defaults ship excluding terminals, which costs you the ability to ask "what was that command I ran earlier". Terminals show secrets in the clear — keys echoed by a command, tokens in an error message, anything pasted — and all of it is OCR'd into plaintext. Delete the terminal block if you want that capability back.

With no config file present, a built-in deny-list applies. git clone && run can never produce zero filtering.

Development

uv venv --python 3.12 && uv pip install -e . pytest
python -m pytest tests/test_tools.py -q

Tests build a synthetic database — you do not need Retrace, or a Mac, to work on this. The fixture deliberately contains a terminal session with a fake API key, a password-manager window, and a banking URL in a browser, so the deny-list tests assert real behaviour rather than passing against data that never had anything to hide.

tests/test_live.py is separate and runs against a real database while Retrace is capturing: concurrency under write load, torn reads, WAL growth, and write refusal. See CONTRIBUTING.md.

Useful scripts:

Script	Purpose
tools/verify_schema.py	Check your database against what the server expects. Run this before filing a bug.
tools/make_fixture.py	Regenerate the synthetic test database.
tools/snapshot.sh	Consistent read-only copy of a live database, via SQLite's backup API.
tools/exercise_tools.py	Drive all six tools over real MCP stdio.

How it reads the database safely

Rule	Why
file:<path>?mode=ro, never immutable=1	The capture daemon writes continuously. immutable lets SQLite skip locking, producing torn reads that fail silently.
PRAGMA query_only = ON	Belt-and-braces alongside mode=ro.
busy_timeout 5000 ms, 2 retries	FTS5 index writes hold locks during capture.
Fresh connection per call	Nothing is held across calls.
isolation_level=None	A long-lived read transaction blocks the WAL checkpointer and the WAL grows unbounded.
No write statement in the package	Enforced by an AST-parsing test.

Verified against a live database under active capture: 200 concurrent calls across 8 threads with zero errors, WAL flat throughout, and CREATE, DELETE, UPDATE, INSERT and journal-mode changes all refused.

Notes on the schema

Observations from a Retrace 0.8.7 install that are not obvious from the outside, and cost time to discover:

• PRAGMA user_version reads 0. Migration state lives in a schema_migrations table, not in user_version.
• Timestamps are epoch milliseconds, not seconds.
• OCR box coordinates are normalised 0–1, not pixels.
• searchRanking is a content-ful FTS5 table (text, otherText, title). Were it contentless, snippet() would raise.
• Roughly half of frames are not in the search index — they have no doc_segment row and are invisible to search_text by design.
• The schema is much larger than the six tools use. audio, transcript_word, event, summary, segment_comment and in_page_url_text all exist. No tool here reads them. Some contain material more sensitive than screen OCR — audio transcripts and calendar participants — so think carefully before adding one that does.
• Video segments live at chunks/YYYYMM/DD/<13-digit-epoch-ms>, extensionless but real MP4.

Other Retrace versions may differ. tools/verify_schema.py will tell you.

License

MIT — see LICENSE.

Not affiliated with Retrace.