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: riven-mcp

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

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.