disco-trooper/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.
Features
- **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
What's New in 1.9.0
- **Large library indexing** - Fetch reads note properties in bulk batches, so indexing thousands of notes finishes instead of stalling
- **Resilient fetch** - Locked or syncing notes are retried per batch and skipped with a report instead of failing the run
- **Cancellable reads** - Long Notes reads time out (JXA_TIMEOUT_MS) and cancellation actually stops the fetch
What's New in 1.8.1
- **Faster list-notes folder filtering** - list-notes now 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
Installation
npm (recommended)
The setup wizard guides you through:
1. Choosing your embedding provider (local or OpenRouter)
2. Configuring API keys if needed
3. Setting up Claude Code integration
4. Indexing your notes
From source
Requirements
- macOS (uses Apple Notes via JXA)
- Bun runtime
- Apple Notes app with notes
Quick Start
Run the command after installation:
The setup wizard starts automatically on first run. Restart Claude Code after setup to use the MCP tools.
Configuration
Configuration stored in ~/.apple-notes-mcp/.env:
| Variable | Description | Default |
|----------|-------------|---------|
| OPENROUTER_API_KEY | OpenRouter API key (enables cloud embeddings) | - |
| EMBEDDING_MODEL | Model name (local or OpenRouter) | Xenova/multilingual-e5-small |
| EMBEDDING_DIMS | Embedding dimensions | 4096 |
| READONLY_MODE | Block all write operations | false |
| INDEX_TTL | Auto-refresh-on-search interval in seconds (disabled when unset) | - |
| SEARCH_REFRESH_TIMEOUT_MS | Max time search waits for refresh before using stale index | 2000 |
| INDEX_JOB_RETENTION_SECONDS | How long completed/failed index jobs remain queryable | 3600 |
| EMBEDDING_BATCH_SIZE | Batch size for embedding generation | 50 |
| NOTES_FETCH_BATCH_SIZE | Batch size for Notes fetch | 100 |
| JXA_TIMEOUT_MS | Max time for a single Notes read in milliseconds | 120000 |
| DEBUG | Enable debug logging | false |
Search Auto-Refresh Policy
- search-notes does **not** force refresh on every request.
- If INDEX_TTL is unset, auto-refresh is disabled and search uses the current index.
- If INDEX_TTL is set, refresh runs only after TTL expiration.
- If refresh fails or takes longer than SEARCH_REFRESH_TIMEOUT_MS, search falls back to stale index results instead of timing out.
To reconfigure:
Embedding Providers
**Local (default)**: Uses HuggingFace Transformers with Xenova/multilingual-e5-small. Free, runs locally, ~200MB download.
**OpenRouter**: Uses cloud API. Fast, requires no local resources, needs API key from openrouter.ai.
See docs/models.md for model comparison.