Skip to main content
Glama
retrace-mcp

retrace-mcp

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.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.

Available Tools

6 tools
app_usageA
Read-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_frameA
Read-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_segmentsA
Read-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_tagsA
Read-onlyIdempotent

List segment tags and how many (visible) segments carry each.

Args: limit: 1-100, default 20.

Inputs: limit. Returns: object

search_textA
Read-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_tagA
Read-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

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    Six tools is well within the ideal range for a focused query-only domain. Each tool serves a distinct analytical purpose without redundancy.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for finding Discord messages. It enables searching guild messages, locating messages from jump URLs, and reading context around results.
      7
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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