apple-notes-mcp
Provides tools for searching, reading, creating, updating, deleting, and managing Apple Notes with semantic search and knowledge graph capabilities.
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.
apple-notes-mcp
MCP server for Apple Notes with semantic search and CRUD operations. An MCP client such as Claude Code can search, read, create, update, and organise your Apple Notes.
Hybrid search (vector + full-text, Reciprocal Rank Fusion) over chunked notes
Incremental and background indexing
Knowledge graph from
#tagsand[[wiki links]]Create, update, delete, move, batch operations, and table cell edits
Local (HuggingFace Transformers) or OpenRouter embeddings
Read-only mode
Release notes: CHANGELOG.md. Some upgrades require running index-notes with mode: "full"; the changelog says when.
Requirements
macOS on Apple Silicon (LanceDB has no native build for Intel Macs)
Bun >= 1.1.0. The executables run with Bun, so npm installs need Bun on
PATHtoo.Apple Notes, with automation permission granted when macOS asks
Related MCP server: Notes MCP
Installation
npm install -g @disco_trooper/apple-notes-mcp
apple-notes-mcpThe first run in a terminal starts the setup wizard: embedding provider, read-only mode, auto-indexing, Claude Code integration, and an initial index. Run apple-notes-mcp-setup later to change settings.
From source:
git clone https://github.com/disco-trooper/apple-notes-mcp.git
cd apple-notes-mcp
bun install
bun run setupClaude Code setup
The setup wizard adds the server to ~/.claude.json (the existing file is backed up to ~/.claude.json.bak). To add it by hand:
{
"mcpServers": {
"apple-notes": {
"command": "apple-notes-mcp",
"args": [],
"env": {}
}
}
}For a source checkout, use "command": "bun" and "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"]. Run the setup wizard once first; the server needs ~/.apple-notes-mcp/.env. Restart Claude Code after setup.
Configuration
Settings live in ~/.apple-notes-mcp/.env. Variables in the MCP client's env block take precedence. Invalid values stop the server at startup.
Variable | Description | Default |
| Use OpenRouter for embeddings ( | - |
| Embedding model | local |
| OpenRouter only; sent as | - |
| Hide and block tools that write to Apple Notes ( |
|
| Seconds after which a search first runs an incremental index; unset or | - |
| Max wait for that refresh before searching the current index |
|
| How long finished index jobs stay queryable |
|
| Texts per embedding batch |
|
| Notes per Apple Notes fetch batch |
|
| Timeout for a single Apple Notes script |
|
| Name of the "Recently Deleted" folder when Apple Notes uses a localized name the server does not recognise | - |
| Debug logging to stderr ( |
|
See docs/models.md for embedding models.
Tools
Notes are addressed as Title, Folder/Title, Account/Folder/Title, or id:xxx. When several notes match, the tool returns an error listing id: values to use.
Category | Tool | Purpose |
Search |
| Hybrid, keyword, or semantic search with optional folder filter |
Read |
| List notes sorted by date or title; without parameters, show index statistics |
Read |
| Full note content as Markdown (optionally HTML) |
Read |
| Tables in a note as rows of cells |
Read |
| All folders |
Index |
| Incremental or full index run, optionally in the background |
Index |
| Start a background index job |
Index |
| Status and progress of a job |
Index |
| Recent jobs |
Index |
| Cancel a running job |
Index |
| Re-index one note |
Index |
| Delete the local index (requires |
Graph |
| Tags with occurrence counts |
Graph |
| Notes with a tag |
Graph |
| Notes related by tags, links, or similarity |
Graph |
| Export the graph as JSON or GraphML |
Write |
| Create a note from Markdown |
Write |
| Replace a note's content |
Write |
| Delete a note (requires |
Write |
| Move a note to another folder |
Write |
| Edit table cells without rewriting the note |
Write |
| Delete several notes or a whole folder (requires |
Write |
| Move several notes or a whole folder |
Write tools are not registered when READONLY_MODE is on. After each write the index is updated for the affected notes; if that fails, the response includes an index sync warning. While an index run is in progress, the update is queued and the write returns right away.
For large libraries, run index-notes with background: true and follow the job with get-index-job. A foreground run sends progress notifications to clients that request them.
Troubleshooting
JXA errors or timeouts: make sure Apple Notes is running and the terminal or MCP client has automation permission (System Settings → Privacy & Security → Automation). For very large folders, lower
NOTES_FETCH_BATCH_SIZEor raiseJXA_TIMEOUT_MS."Embedding model changed": the index was built with another model or dimensions. Run
purge-index, thenindex-noteswithmode: "full".Skipped notes: locked or still-syncing notes cannot be read. Unlock them or wait for iCloud sync, then reindex.
Slow first search: the local model is downloaded and loaded on first use.
Write tools missing or "tool not found":
READONLY_MODEis on. SetREADONLY_MODE=falseand restart the client.
Development
bun run check # type check
bun run test # tests (vitest; do not use `bun test`)
bun run test:coverage # tests with coverage
bun run dev # watch mode
DEBUG=true bun run startLicense
MIT
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
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables semantic search and retrieval of Apple Notes content, allowing AI assistants to access, search, and create notes using on-device embeddings.2MIT
- 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
- AlicenseAqualityDmaintenanceMCP server for Apple Notes with semantic search (on-device embeddings via all-MiniLM-L6-v2), full-text search, complete CRUD operations, folder management, and fuzzy title matching. 10 tools. Runs fully locally on macOS — no API keys required.1019 npm14MIT
- AlicenseAqualityBmaintenanceAn MCP server that enables LLM agents to list, read, create, update, delete, and search Apple Notes on macOS.613 npmAGPL 3.0