macnotes-mcp

macnotes-mcp is a fork of RhetTbull/macnotesapp focused on running Apple Notes as a production-ready MCP server.

It provides:

• Async, cache-backed reads
• Background queued writes to Apple Notes
• macOS LaunchAgent service support
• Easy integration with mcporter and OpenClaw

Fork Attribution

This project is forked from:

• Upstream: RhetTbull/macnotesapp
• Upstream repo: https://github.com/RhetTbull/macnotesapp

The original Python/CLI Notes automation remains available, and this fork adds MCP-first architecture and service tooling.

Requirements

• macOS (Apple Notes automation is macOS-only)
• Python 3.10-3.13
• uv (recommended) for env/dependency management
• Apple Notes.app installed and accessible

Optional:

• mcporter for MCP client setup and testing
• OpenClaw if you want agent integration

Quick Start

Clone and install:

git clone https://github.com/zorrobyte/macnotes-mcp.git
cd macnotes-mcp
uv sync

Run MCP over stdio:

uv run notes-mcp

Run MCP over local HTTP (streamable-http):

MACNOTES_MCP_TRANSPORT=streamable-http MACNOTES_MCP_HOST=127.0.0.1 MACNOTES_MCP_PORT=8765 uv run notes-mcp-daemon

Run as a macOS Background Service

Install as LaunchAgent:

./scripts/install_service.sh

Uninstall:

./scripts/uninstall_service.sh

Service details:

• Label: com.zorrobyte.macnotes-mcp
• Default endpoint: http://127.0.0.1:8765/mcp
• Logs: ~/Library/Logs/macnotes-mcp/

Check service:

launchctl print "gui/${UID}/com.zorrobyte.macnotes-mcp"

Tail logs:

tail -f ~/Library/Logs/macnotes-mcp/launchd.stderr.log
tail -f ~/Library/Logs/macnotes-mcp/service.log

MCP Client Setup

mcporter + OpenClaw helper

Use the helper script:

./scripts/setup_mcporter.sh

This does two things:

• Registers MCP server macnotes-mcp in ~/.mcporter/mcporter.json
• Disables OpenClaw bundled apple-notes skill to avoid overlap

Custom server name/url:

./scripts/setup_mcporter.sh my-notes http://127.0.0.1:8765/mcp

Manual mcporter setup

mcporter config add macnotes-mcp --url http://127.0.0.1:8765/mcp --transport http --scope home
mcporter call macnotes-mcp.notes_health --json

MCP Tools

The server exposes:

• notes_health
• notes_accounts
• notes_sync_full
• notes_sync_incremental
• notes_sync_status
• notes_queue_status
• notes_job_status
• notes_job_wait
• notes_list
• notes_read
• notes_create
• notes_update
• notes_delete
• notes_move

Configuration

Config source priority:

1. Environment variables
2. ~/.config/macnotes-mcp/service.toml
3. Built-in defaults

Example config template:

• deploy/config/service.example.toml

Main environment variables:

• MACNOTES_MCP_TRANSPORT = stdio | sse | streamable-http
• MACNOTES_MCP_HOST (default 127.0.0.1)
• MACNOTES_MCP_PORT (default 8000)
• MACNOTES_MCP_MOUNT_PATH (default /)
• MACNOTES_MCP_BOOTSTRAP_SYNC (default true)
• MACNOTES_MCP_POLL_INTERVAL_SECONDS (default 120)
• MACNOTES_MCP_CACHE_DB_PATH (optional override)
• MACNOTES_MCP_LOG_LEVEL (default INFO)
• MACNOTES_MCP_LOG_DIR (optional override)
• MACNOTES_MCP_LOCK_PATH (optional override)

Architecture Summary

• Source of truth: Apple Notes via ScriptingBridge/Apple Events
• Cache: local SQLite for fast reads and search
• Writes: queued background jobs for non-blocking behavior
• Sync: bootstrap full sync + periodic refresh loop

Important:

• Direct writes to Apple Notes private SQLite (NoteStore.sqlite) are not used.
• This avoids corruption/sync issues from private schema assumptions.

Permissions and macOS Notes Automation

On first run, macOS may prompt for Automation permissions (Terminal/Python controlling Notes).

If calls fail:

• Open System Settings -> Privacy & Security -> Automation
• Ensure your invoking app/runtime is allowed to control Notes
• Re-run service or command

Troubleshooting

Health check:

mcporter call macnotes-mcp.notes_health --json

If endpoint is unreachable:

• Verify service is running with launchctl print ...
• Confirm listener port 8765 is open
• Check launchd.stderr.log and service.log

If sync is slow on first run:

• Large Apple Notes libraries can take time for initial bootstrap
• Use notes_sync_status to track cache size and sync state

If OpenClaw still uses old notes skill:

openclaw config set skills.entries.apple-notes.enabled false

Legacy CLI (from upstream)

This fork still includes upstream CLI entrypoints:

• notes
• macnotesapp Python API modules

The main focus of this fork is MCP service usage.

Development

Install dev environment:

uv sync

Run tests:

uv run pytest -v -s tests/

Run daemon locally:

uv run notes-mcp-daemon --transport streamable-http --host 127.0.0.1 --port 8765

License

MIT (same as upstream).