macnotes-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
mcporterand OpenClaw
Fork Attribution
This project is forked from:
Upstream:
RhetTbull/macnotesappUpstream repo: https://github.com/RhetTbull/macnotesapp
The original Python/CLI Notes automation remains available, and this fork adds MCP-first architecture and service tooling.
Related MCP server: apple-mcp
Requirements
macOS (Apple Notes automation is macOS-only)
Python 3.10-3.13
uv(recommended) for env/dependency managementApple Notes.app installed and accessible
Optional:
mcporterfor MCP client setup and testingOpenClaw if you want agent integration
Quick Start
Clone and install:
git clone https://github.com/zorrobyte/macnotes-mcp.git
cd macnotes-mcp
uv syncRun MCP over stdio:
uv run notes-mcpRun 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-daemonRun as a macOS Background Service
Install as LaunchAgent:
./scripts/install_service.shUninstall:
./scripts/uninstall_service.shService details:
Label:
com.zorrobyte.macnotes-mcpDefault endpoint:
http://127.0.0.1:8765/mcpLogs:
~/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.logMCP Client Setup
mcporter + OpenClaw helper
Use the helper script:
./scripts/setup_mcporter.shThis does two things:
Registers MCP server
macnotes-mcpin~/.mcporter/mcporter.jsonDisables OpenClaw bundled
apple-notesskill to avoid overlap
Custom server name/url:
./scripts/setup_mcporter.sh my-notes http://127.0.0.1:8765/mcpManual 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 --jsonMCP Tools
The server exposes:
notes_healthnotes_accountsnotes_sync_fullnotes_sync_incrementalnotes_sync_statusnotes_queue_statusnotes_job_statusnotes_job_waitnotes_listnotes_readnotes_createnotes_updatenotes_deletenotes_move
Configuration
Config source priority:
Environment variables
~/.config/macnotes-mcp/service.tomlBuilt-in defaults
Example config template:
deploy/config/service.example.toml
Main environment variables:
MACNOTES_MCP_TRANSPORT=stdio|sse|streamable-httpMACNOTES_MCP_HOST(default127.0.0.1)MACNOTES_MCP_PORT(default8000)MACNOTES_MCP_MOUNT_PATH(default/)MACNOTES_MCP_BOOTSTRAP_SYNC(defaulttrue)MACNOTES_MCP_POLL_INTERVAL_SECONDS(default120)MACNOTES_MCP_CACHE_DB_PATH(optional override)MACNOTES_MCP_LOG_LEVEL(defaultINFO)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 --jsonIf endpoint is unreachable:
Verify service is running with
launchctl print ...Confirm listener port
8765is openCheck
launchd.stderr.logandservice.log
If sync is slow on first run:
Large Apple Notes libraries can take time for initial bootstrap
Use
notes_sync_statusto track cache size and sync state
If OpenClaw still uses old notes skill:
openclaw config set skills.entries.apple-notes.enabled falseLegacy CLI (from upstream)
This fork still includes upstream CLI entrypoints:
notesmacnotesappPython API modules
The main focus of this fork is MCP service usage.
Development
Install dev environment:
uv syncRun tests:
uv run pytest -v -s tests/Run daemon locally:
uv run notes-mcp-daemon --transport streamable-http --host 127.0.0.1 --port 8765License
MIT (same as upstream).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
1Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI assistants like Claude to access and manipulate Apple Notes on macOS, allowing for retrieving, creating, and managing notes through natural language interactions.84MIT
- AlicenseBqualityCmaintenanceMCP server for macOS Apple apps. Enables read/write access to Notes, Reminders, Calendar, Contacts, and Safari using SQLite and JXA, all running locally.2817 npm4MIT
- AlicenseAqualityDmaintenanceComprehensive Apple Notes MCP server for local macOS note management.147,035 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for macOS that enables creating, reading, and searching Apple Notes programmatically through tools like find, get by title or ID, and create.7,035 npmMIT