mac-stickies-mcp

A local MCP server for reading and safely editing Apple Stickies on macOS.

Status: 1.0.0 is the stable contract for one currently open Stickies app on one screen. It is published on PyPI.

Runs locally through MCP stdio. Note contents stay on your Mac; writes check for conflicts and keep local backups.

Quick start

uv tool install mac-stickies-mcp==1.0.0
mac-stickies-mcp doctor
codex mcp add mac-stickies -- mac-stickies-mcp

Reading and searching do not require Accessibility. Writing does; doctor identifies the executable to authorize. Deletion is recoverable, but brings Stickies to the foreground and requires explicit allow_foreground: true.

Related MCP server: @cardmagic/notes

For MCP clients and agents

This is a local stdio server. Configure your MCP host to launch:

command: mac-stickies-mcp

The host's configuration format differs, and installing the server or granting Accessibility always requires the user's approval. Once connected, use the tool schemas returned by the server as the machine-readable source of truth.

• Read or search, then call get_note before choosing a note to change.

• For text writes, pass that note's current expected_version; on conflict, re-read rather than force an overwrite.

• Before deletion, warn that Stickies will come to the foreground and obtain explicit user approval before setting allow_foreground: true.

• Do not bypass these safeguards with GUI automation, AppleScript, or direct .rtfd file changes while Stickies is open.

Start with the documentation guide. The public tool contract is in docs/reference/mcp-tools.md; internal behaviour and safety rules are in docs/specification.md. The reproducible running-App write study is in docs/research/compatibility-study.md. For local development rules, see AGENTS.md and docs/development.md.

Available tools

Writes require the expected_version returned by get_note. With a running, visible Stickies note that version starts with ui-sha256: and the mutation is performed through Accessibility; Stickies, not this package, owns the later disk save. A conflict or unsaved human UI edit is reported as a tool error; no data is overwritten. Every completed write has an operation_id that can be passed to undo.

The server keeps backups in ~/Library/Application Support/mac-stickies-mcp/backups/. Backups are local and private to the current user, retained for up to 30 days and 100 per note. The original Stickies files remain under the user's Stickies container.

Stable visual-state boundary

The stable API deliberately does not set note color, size, or rich-text styles. Stickies Accessibility exposes commands to change some of these values, but it does not reliably expose a current note color. Those values therefore cannot yet receive the same before/after backup and undo guarantees as text. They are deferred to a read-first state compatibility study. restore_note creates a new note with a new UUID; it restores backed-up text, not an unverifiable visual state.

create_note has a strict safety guard: if Stickies does not surface a new window with a distinct document UUID, it returns create_unidentified without writing into the currently active note. It waits up to three seconds for the package to appear, then returns persistence: "persisted" or "pending"; clients must wait for the latter before a file-dependent follow-up such as deletion. Successful responses include ui_exposure_ms and persistence_wait_ms for diagnostics.

Stable-scope limitations

• delete_note is recoverable, but the only verified Stickies deletion route brings Stickies and the target note to the foreground. It requires explicit allow_foreground: true, so clients must warn the user before it can interrupt work or leave the desktop visible after closing the last focused note.

• move_note changes only a UUID-matched window's AXPosition, verifies the result, and does not activate or raise Stickies. It requires expected_position from get_note_layout, so a human drag is a safe layout_conflict rather than an overwrite. Color, resizing, floating, collapsed state, multi-display placement, and layout commands remain unimplemented.

• Never remove or replace a .rtfd package while Stickies is running. The App can retain an in-memory copy and later overwrite or conflict with the file.

Accessibility setup for writes

Reading and searching do not require Accessibility. Editing a note while Stickies is open does: the server uses macOS Accessibility to update the exact visible note rather than replacing its RTF file behind the app's back.

After installation, run this once in the same environment that will launch the MCP server:

mac-stickies-mcp doctor

It requests the macOS consent prompt and prints the executable that macOS must trust. In System Settings → Privacy & Security → Accessibility, enable that reported executable. If an update changes the executable identity, run doctor again and repeat the one-time approval. A missing grant causes a safe accessibility_required error; no note is changed.

Client configuration and local development

For development from a source checkout, use the project's installed CLI so the Accessibility client has a stable executable:

uv tool install mac-stickies-mcp
mac-stickies-mcp doctor

Then add it to a local Codex client:

codex mcp add mac-stickies -- mac-stickies-mcp
codex mcp list

The equivalent ~/.codex/config.toml entry is:

[mcp_servers.mac-stickies]
command = "mac-stickies-mcp"
default_tools_approval_mode = "writes"

writes keeps read tools convenient while asking before mutation tools. In the ChatGPT desktop app, the same shared configuration can also be added from Settings → MCP servers → Add server, selecting STDIO and entering mac-stickies-mcp as the command.

Uninstall and local data

uv tool uninstall mac-stickies-mcp

Uninstalling the tool does not touch Apple Stickies or its backups. To remove MCP-only recovery data, first inspect ~/Library/Application Support/mac-stickies-mcp/backups/, then move the mac-stickies-mcp folder to Trash manually if it is no longer needed. Remove the corresponding Accessibility entry in System Settings → Privacy & Security → Accessibility if you no longer want the executable to control Stickies.

Development

uv sync --all-groups
uv run python -m unittest discover -s tests -v
uv run ruff check .
uv run ruff format --check .

For a local development connection, use the project's installed CLI at .venv/bin/mac-stickies-mcp as the MCP stdio command. For an ephemeral PyPI run, use uvx mac-stickies-mcp.

The prototype exporter lives at scripts/export_stickies.py. It reads local Stickies and writes a Markdown snapshot under work/, which is ignored by Git.

Project layout

src/mac_stickies_mcp/  Package source
tests/                 Automated tests and non-private fixtures
scripts/               Development-only helper scripts
docs/                  Public reference, maintainer docs, and research evidence
work/                  Local generated files; never committed

License

MIT