retrace-mcp
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., "@retrace-mcp search my screen history for 'quarterly planning'"
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.
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.
Related MCP server: local-dev-tools
Install
git clone https://github.com/calvingunther66/retracemcpclaude.git
cd retracemcpclaude
bash install.shInstalls 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 retraceTools
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 |
| Full-text search over screen OCR. One hit per frame with a |
| Capture segments — one contiguous stretch in one app window — with start, end and duration. |
| One frame with its OCR text boxes and parent segment. |
| Time per app across a window, ordered descending, with display names. |
| 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 = trueKey | Effect |
| App bundle IDs hidden from every tool. |
| Substrings matched against the segment's browser URL. |
| Substrings matched against the window title. |
| Honour Retrace's own |
| Drop rows whose snippet is |
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 -qTests 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 |
| Check your database against what the server expects. Run this before filing a bug. |
| Regenerate the synthetic test database. |
| Consistent read-only copy of a live database, via SQLite's backup API. |
| Drive all six tools over real MCP stdio. |
How it reads the database safely
Rule | Why |
| The capture daemon writes continuously. |
| Belt-and-braces alongside |
| FTS5 index writes hold locks during capture. |
Fresh connection per call | Nothing is held across calls. |
| 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_versionreads 0. Migration state lives in aschema_migrationstable, not inuser_version.Timestamps are epoch milliseconds, not seconds.
OCR box coordinates are normalised 0–1, not pixels.
searchRankingis 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_segmentrow and are invisible tosearch_textby design.The schema is much larger than the six tools use.
audio,transcript_word,event,summary,segment_commentandin_page_url_textall 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.
Available Tools
6 toolsapp_usageARead-onlyIdempotent
Time spent per app over a window, from summed segment durations.
Args: start: ISO 8601 local start of the window. end: ISO 8601 local end of the window. limit: 1-100, default 20.
Inputs: end (required), start (required), limit. Returns: object
get_frameARead-onlyIdempotent
Fetch one frame with its OCR text boxes and parent segment context.
Box geometry (leftX, topY, width, height) is expressed as normalised fractions of the frame, in the range 0.0-1.0 — not pixels. Multiply by the video's width/height to get pixel coordinates.
Args: frame_id: The frame's numeric id. limit: Max OCR node boxes to return, 1-100, default 20.
Inputs: frame_id (required), limit. Returns: object
list_segmentsARead-onlyIdempotent
List capture segments (one contiguous stretch in one app window).
Args: start: Optional ISO 8601 local lower bound on segment start. end: Optional ISO 8601 local upper bound on segment start. bundle_id: Optional single app bundle ID to filter to. limit: 1-100, default 20.
Inputs: end, limit, start, bundle_id. Returns: object
list_tagsARead-onlyIdempotent
List segment tags and how many (visible) segments carry each.
Args: limit: 1-100, default 20.
Inputs: limit. Returns: object
search_textARead-onlyIdempotent
Full-text search across OCR'd screen content.
Args:
query: FTS5 match expression, e.g. invoice, "exact phrase",
budget NEAR/5 forecast, sched*.
start: Optional ISO 8601 local lower bound on frame time.
end: Optional ISO 8601 local upper bound on frame time.
bundle_ids: Optional allow-list of app bundle IDs to search within.
limit: 1-100, default 20.
Inputs: query (required), end, limit, start, +1 more. Returns: object
segments_by_tagARead-onlyIdempotent
List segments carrying a given tag name.
Args: tag: Exact tag name, as returned by list_tags. limit: 1-100, default 20.
Inputs: tag (required), limit. 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
Each tool targets a distinct query type: segment listing, app usage aggregation, tag listing, segments-by-tag, text search, and frame retrieval. The purposes are clearly differentiated, with no apparent overlap.
Tool names follow a mix of conventions: list_* and get_* and search_text are verb_noun, while app_usage and segments_by_tag are noun phrases. This mixed pattern is still readable but lacks a single consistent style.
Six tools is well within the ideal range for a focused query-only domain. Each tool serves a distinct analytical purpose without redundancy.
The surface covers the core query needs: segment listing, app usage, tag filtering, text search, and frame detail. Minor gaps exist, such as no dedicated get_segment tool or tag management, but these are not critical for the likely read-only intent.
Maintenance
Related MCP Connectors
Read-only MCP server for the Durable Agent Directory: search and compare agent-infrastructure tools.
Search MCP servers, MCP clients and AI agents, and retrieve listing details. Free, read-only access.
MCP server for querying Forkast documentation
Read-only MCP access to authorized Vocci sessions, notes, files, and memory search.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server for finding Discord messages. It enables searching guild messages, locating messages from jump URLs, and reading context around results.71MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server providing SQLite querying, port checking, and git diff summary tools for local development.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for unified full-text search across chat histories from Claude Code, Codex, Cursor CLI, and Antigravity CLI, using SQLite FTS5. Provides read-only tools to search sessions, list conversations, and retrieve session details.MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for TraceFact that lets agents list trace runs, fetch run details, and retrieve reliability reports from a local store.Apache 2.0