Skip to main content
Glama
openrhyme-mcp

openrhyme-mcp

Official
by OpenRhyme

openrhyme-mcp

A thin Model Context Protocol server that exposes the timeline captured by the OpenRhyme engine to any agent — Claude, local models, your own scripts — over stdio.

Status: MVP implemented on this branch — a stdio MCP server exposing the engine's raw event timeline and app-allowlist controls, tested against a fixture store and a fake engine binary. The engine it depends on (OpenRhyme/OpenRhyme) has its Part 1 (capture) complete. Pending: dogfooding against a live engine capture; richer retrieval (sessions, search, embeddings) is future work.

What it is, and is not

OpenRhyme is a local-first, open-source "Computer History" for macOS: a Swift daemon reads your activity through the accessibility API, stores it in tiered SQLite, and compacts it without any bundled model. This repository is the agent-facing door to that data. It:

  • speaks MCP over stdio, so any agent host (Claude Desktop, Claude Code, …) can spawn it;

  • reads the engine's SQLite tiers read-only;

  • shells out to the openrhyme CLI (openrhyme <cmd> --json) for control commands;

  • contains no capture logic, holds no macOS permissions, and makes no network calls.

Everything stays on your machine. The agent host that spawns this server is the trust boundary — it sees exactly what the tools return, nothing more.

Related MCP server: Rob Desktop Commander

How the pieces fit

 openrhyme daemon (Swift, launchd)  ──writes──▶  ~/Library/Application Support/OpenRhyme/*.sqlite
                                                              │
                                                   read-only  │        `openrhyme … --json`
                                                              ▼                 │
                          agent host ──stdio──▶  openrhyme-mcp (this repo) ─────┘

The full process topology, the CLI/JSON contract, and the store layout are specified in the engine repo: docs/engine-interface.md. That document is the contract this server implements; it is not duplicated here.

Tools & resources

MCP tool

Returns

events(since, until, kinds, app, limit, max_value_chars)

raw events in a time window: {"events": [...], "count": n}

status()

engine trust/daemon/store status, plus this server's schema and db info

apps()

the capture allowlist and currently running apps

allow_app(bundle_id) / deny_app(bundle_id)

add/remove an app from the capture allowlist, by bundle identifier

MCP resource

Contents

openrhyme://events/recent

the last 15 minutes of raw events, as JSON Lines

Richer retrieval (sessions, full-text search, embeddings) is future work, not yet built.

Development

Requires Python 3.12+ and uv.

make sync        # uv sync --all-groups
make check       # ruff + mypy (strict) + pytest
uv run openrhyme-mcp   # serve on stdio (Ctrl-C to stop)

Tests run in-process against a fixture database and a fake openrhyme script; they never need the real engine or a macOS permission. CI runs on Ubuntu and macOS 26.

Using it with an agent

With the engine built (../OpenRhyme, make build) and on PATH — or pointed to via OPENRHYME_BIN:

claude mcp add openrhyme -- uv run --directory /path/to/openrhyme-mcp openrhyme-mcp

Then ask: "What was I doing between 2 and 3 pm?" — the model calls events(since="…", until="…"). Tools: events, status, apps, allow_app, deny_app; resource: openrhyme://events/recent. Environment: OPENRHYME_DATA_DIR (engine data dir), OPENRHYME_BIN (engine binary).

License

MIT — see LICENSE.

Available Tools

5 tools
allow_appA

Add an app to the capture allowlist by bundle identifier (e.g. com.apple.Safari). Takes effect within a few seconds; the daemon reloads its config on each heartbeat.

Inputs: bundle_id (required). Returns: object

appsC

The capture allowlist and the currently running apps (with bundle identifiers, whether each is allowlisted, and whether it is an Electron app).

Inputs: no named parameters. Returns: object

deny_appA

Remove an app from the capture allowlist by bundle identifier.

Inputs: bundle_id (required). Returns: object

eventsA

Raw activity events between since and until, oldest first.

Returns {"events": [...rows...], "count": N}; each row's keys are the event columns (bundle_id, app_name, window_title, kind, value, ...) and a local-ISO "time" field. Read result["events"] for the rows.

Times accept 2h / 30m / 1d (that long ago), unix seconds, or ISO-8601. kinds filters by event kind (e.g. app.activated, window.focused, context.snapshot, element.value_changed); app by bundle identifier. value/selected_text are cut to max_value_chars (0 = full text). limit ≤ 2000.

Inputs: since (required), app, kinds, limit, +2 more. Returns: object

statusA

Engine status (trust, daemon liveness, event count, allowlist) plus this server's view: supported schema, database path and whether it exists.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: events queries captured activity data, status reports engine/server state, apps lists the allowlist and running apps, and allow_app/deny_app make targeted allowlist changes. There is no functional overlap between any of these tools.

    Naming Consistency4/5

    The read-only tools use noun-style names (events, status, apps) while the mutations use verb_noun style (allow_app, deny_app). This is fairly predictable and readable, though not as uniform as a single verb_noun convention throughout.

    Tool Count5/5

    Five tools is well-scoped for this server's purpose: querying activity events, checking engine status, listing apps, and managing the allowlist. Each tool earns its place without the surface feeling bloated or thin.

    Completeness5/5

    The core workflows are fully covered: retrieve activity data, inspect engine health, view the allowlist, and add or remove apps from it. Since events are an append-only raw log, update/delete operations are not expected here, so there are no obvious gaps.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to search, record, correct, and review the provenance and version history of memories, and to obtain answers composed from guarded context in which private values are replaced by placeholders and resolved locally on the device. Exposes these capabilities through dependency-free tools over stdio.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP stdio bridge that lets compatible agents query a local, provenance-first memory graph, fetch source-versioned text, inspect retrieval, check service health, and report usefulness feedback.
      1
      MIT