Apple Notes Mcp

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.

- Chunk-Based Search- Long notes split into chunks for accurate matching
- Query Caching- 60x faster repeated searches
- Knowledge Graph- Tags, links, and related notes discovery
- Hybrid Search- Vector + keyword search with Reciprocal Rank Fusion
- Semantic Search- Find notes by meaning, not keywords
- Full CRUD- Create, read, update, delete, and move notes
- Incremental Indexing- Re-embed only changed notes
- Background Index Jobs- Async full/incremental indexing with progress polling
- Dual Embedding- Local HuggingFace or OpenRouter API

- Fasterlist-notesfolder filtering-list-notesnow queries only the requested folder instead of scanning all notes first
- Duplicate folder name correctness- Folder filtering now aggregates matching folders across accounts
- Large vault performance- Folder-scoped listing is significantly faster on larger note libraries

npm install -g @disco_trooper/apple-notes-mcp apple-notes-mcp

- Choosing your embedding provider (local or OpenRouter)
- Configuring API keys if needed
- Setting up Claude Code integration
- Indexing your notes

git clone https://github.com/disco-trooper/apple-notes-mcp.git cd apple-notes-mcp bun install bun run start

- macOS (uses Apple Notes via JXA)
- Bunruntime
- Apple Notes app with notes

apple-notes-mcp setup # or from source: bun run setup

OpenRouter: Uses cloud API. Fast, requires no local resources, needs API key fromopenrouter.ai.

Seedocs/models.mdfor model comparison.

query: "meeting notes from last week" folder: "Work" # optional, filter by folder limit: 10 # default: 20 mode: "hybrid" # hybrid, keyword, or semantic include_content: false # include full content vs preview

sort_by: "modified" # created, modified, or title (default: modified) order: "desc" # asc or desc (default: desc) limit: 10 # max notes to return (1-100) folder: "Work" # filter by folder (case-insensitive)

title: "My Note" # or "Work/My Note" for disambiguation include_html: false # include raw HTML (default: false)

{ "tableCount": 2, "tables": [{ "index": 0, "rows": [["Header1", "Header2"], ["Val1", "Val2"]], "formatting": [[{"bold": true}, {"bold": true}], ...] }] }

mode: "incremental" # incremental (default) or full force: false # force reindex even if TTL hasn't expired background: false # optional; defaults to false (synchronous mode)

Usemode: "full"to create the chunk index for better long-note search. First full index takes longer as it generates chunks, but subsequent searches run fast.

For large vaults, prefer background indexing:

mode: "full" # full or incremental

Returns a job snapshot withid,status, andprogress. Progress updates in smaller steps across fetch, embed, and persist phases.

Poll until status iscompleted,failed, orcancelled. You may seecancellingas a transitional status.

Requests best-effort cancellation for a running job. Cancellation is cooperative:

- A long-running step must reach a cancellation checkpoint.
- Partial work may remain.
- Start a new job after the current one reachescancelled.

Re-index a single note after manual edits.

title: "New Note" content: "# Heading\n\nMarkdown content..." folder: "Work" # optional, defaults to Notes

After create, update, delete, or move, the server auto-syncs vector and chunk indexes in best-effort mode. If sync partly fails, the tool response includes anindex sync warning. Runreindex-noteorindex-notes.

title: "My Note" content: "Updated markdown content..." reindex: true # re-embed after update (default: true)

title: "My Note" confirm: true # must be true to delete

title: "My Note" folder: "Archive"

titles: ["Note 1", "Note 2"] # OR folder: "Old Project" confirm: true # required for safety

titles: ["Note 1", "Note 2"] # OR sourceFolder: "Old" targetFolder: "Archive" # required

Clear all indexed data. Use when switching embedding models or to fix corrupted index.

After purging, runindex-notesto rebuild.

tag: "project" folder: "Work" # optional limit: 20 # default: 20

title: "My Note" types: ["tag", "link", "similar"] # default: all limit: 10 # default: 10

Export knowledge graph for visualization.

format: "json" # json or graphml folder: "Work" # optional filter

- json- For custom visualization (D3.js, web apps)
- graphml- For professional tools (Gephi, yEd, Cytoscape)

The setup wizard automatically adds apple-notes-mcp to Claude Code. Runapple-notes-mcpafter installation.

{ "mcpServers": { "apple-notes": { "command": "apple-notes-mcp", "args": [], "env": {} } } }

{ "mcpServers": { "apple-notes": { "command": "bun", "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"], "env": {} } } }

After setup, use natural language with Claude:

- "Search my notes for project ideas"
- "Create a note called 'Meeting Notes' in the Work folder"
- "What's in my note about vacation plans?"
- "Move the 'Old Project' note to Archive"
- "Index my notes" (after adding notes in Apple Notes)

Use full path formatFolder/Note Titlewhen multiple notes share the same name.

Local embeddings download the model on first use (~200MB). Subsequent searches run fast.

SetREADONLY_MODE=falsein.envto enable write operations.

Runindex-notesto update the search index. Usemode: fullif incremental misses changes.

"iCloud account not available" /Can't get account "iCloud"

This error comes from a different Apple Notes MCP implementation that uses toolsearch_notesand argumentKeywords.

If your client callssearch_noteswithKeywords, point your MCP config toapple-notes-mcpand restart the client.

Ensure Apple Notes runs and contains notes. Grant automation permissions when prompted.

"JSON Parse error: Unexpected identifier undefined"

This usually means the indexing process ran out of memory. Try:
- Close other applications to free memory
- SetEMBEDDING_BATCH_SIZE=25in.envto reduce memory usage
- Restart Apple Notes app
- Runindex-notesagain

- Locked- Unlock them in Apple Notes if you want them indexed
- Syncing- Wait for iCloud sync to complete, then reindex
- Corrupted- Try copying content to a new note and deleting the old one

The indexer will report which notes were skipped and continue with the rest.

# Type check bun run check # Run tests bun run test # Run with coverage bun run test:coverage # Run with debug logging DEBUG=true bun run start # Watch mode bun run dev

- Runbun run checkbefore submitting
- Add tests for new functionality
- Update documentation as needed

A server for the Scrapbox/CoSense platform to retrieve, list, search, and create pages.

Integrates Model Context Protocol (MCP) with Obsidian, allowing AI assistants to interact with your notes and vault.

The visual deal tracker for AI agents to search pipelines, log notes, qualify leads, and export live reports.

An MCP server for document ingestion, chunking, semantic search, and note management.

A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.

Connect Claude or ChatGPT to your MarkIt library to search, save, and set reminders across everything you've saved.

A service for reading, writing, and managing markdown documentation with frontmatter metadata.

Connect your AI assistant to your personal knowledge base. Search, save links, create notes and to-dos. AI processes everything automatically.

An MCP server for interacting with Obsidian notes. Requires the OBSIDIAN_VAULT_PATH environment variable to be set.

Interact with your Obsidian vault using natural language.