# disco-trooper/apple-notes-mcp [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/disco-trooper/apple-notes-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 96  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/disco-trooper-apple-notes-mcp

## Description
Apple Notes MCP with semantic search, hybrid vector+keyword search, full CRUD operations, and incremental indexing. Uses JXA for native macOS integration.

## Tools
Capabilities this server exposes over MCP:

- **search-notes** — Hybrid vector + fulltext search.
- **list-notes** — List notes with sorting and filtering. Without parameters, shows index statistics.
- **list-folders** — List all Apple Notes folders.
- **get-note** — Get note content by title.
- **get-tables** — Extract structured table data from a note.
- **index-notes** — Index notes for semantic search.
- **start-index-job** — ```
- **get-index-job** — ```
- **list-index-jobs** — ```
- **cancel-index-job** — ```
- **reindex-note** — Re-index a single note after manual edits.
- **create-note** — Create a note in Apple Notes.
- **update-note** — Update an existing note.
- **delete-note** — Delete a note (requires confirmation).
- **move-note** — Move a note to another folder.
- **batch-delete** — Delete multiple notes at once.
- **batch-move** — Move multiple notes to a target folder.
- **purge-index** — Clear all indexed data. Use when switching embedding models or to fix corrupted index.
- **list-tags** — List all tags with occurrence counts.
- **search-by-tag** — Find notes with a specific tag.
- **related-notes** — Find notes related to a source note.
- **export-graph** — Export knowledge graph for visualization.

## Claude Desktop Quick Installation
Install path inferred — verify against the README before running it. Uses `npx` (confidence: medium):

```json
"mcpServers": {
  "apple-notes-mcp": {
    "command": "npx",
    "args": ["-y","@disco_trooper/apple-notes-mcp"]
  }
}
```

## Documentation

## What disco-trooper/apple-notes-mcp MCP server does

disco-trooper/apple-notes-mcp MCP server exposes Apple Notes operations to an MCP-compatible client. It can retrieve notes by title, list folders, filter and sort note listings, extract table data, and search note content. Search supports keyword, semantic, or hybrid modes, with hybrid search combining vector and full-text results.

The server also provides write operations for creating, editing, deleting, moving, and batch-managing notes. Destructive actions require confirmation, and write operations can trigger best-effort synchronization of the search indexes. A read-only mode is available through configuration when write access should be blocked.

Its discovery features include tag counts, tag-based search, related-note lookup based on tags, links, or similarity, and knowledge-graph export. These features are useful for navigating a note library beyond exact-title or keyword matches.

## How it works

The project runs on macOS and accesses Apple Notes through JXA, so Apple Notes and its notes must be available on the host machine. It maintains local indexes for search and can split long notes into chunks to improve matching. Incremental indexing reprocesses changed notes instead of rebuilding everything, while a full index can be created for broader long-note coverage.

Embedding generation defaults to the local `Xenova/multilingual-e5-small` Hugging Face model, which downloads approximately 200 MB and does not require a cloud API key. OpenRouter can be selected for cloud embeddings by providing `OPENROUTER_API_KEY`. Search results may use a current or stale index depending on the refresh configuration and timeout behavior.

For larger libraries, indexing can run as a background job. The client can start a full or incremental job, inspect its progress, list retained jobs, and request cancellation. Cancellation is cooperative, so partial work may remain.

## Setup and configuration

Install the published npm package and run its `apple-notes-mcp` command. The first-run wizard selects the embedding provider, configures any needed API key, offers Claude Code integration, and starts indexing. The repository also documents a source setup using Bun with `bun install` followed by `bun run start`.

Configuration is stored in `~/.apple-notes-mcp/.env`. Relevant settings control the embedding model and dimensions, read-only behavior, index refresh timing, search refresh timeout, background-job retention, embedding batch size, and debug logging. `INDEX_TTL` is optional; when it is not set, searches use the existing index without automatic refresh. The `apple-notes-mcp setup` command can be used to reconfigure the installation.

## Tools and capabilities

The available MCP tools cover these areas:

- Search and retrieval with `search-notes`, `list-notes`, `list-folders`, `get-note`, and `get-tables`.
- Index creation and maintenance with `index-notes`, `reindex-note`, `purge-index`, and the asynchronous index-job tools.
- Note management with `create-note`, `update-note`, `delete-note`, `move-note`, `batch-delete`, and `batch-move`.
- Organization and relationship discovery with `list-tags`, `search-by-tag`, `related-notes`, and `export-graph`.

`get-note` accepts a title and can use a folder-qualified title for disambiguation. `get-tables` returns rows and formatting information for tables found in a note. `purge-index` requires confirmation and should be followed by indexing to restore search data.

## Limitations and notes

disco-trooper/apple-notes-mcp MCP server is macOS-specific because it relies on Apple Notes through JXA. The project requires the Bun runtime even when installed from npm. Semantic search depends on an index, so newly changed notes may require automatic refresh, manual reindexing, or a full indexing job before they appear in expected results.

OpenRouter embeddings require the user's API key; the local embedding option avoids that requirement but uses local resources and requires the model download. Index refresh during search is bounded by `SEARCH_REFRESH_TIMEOUT_MS`; if refresh fails or exceeds that limit, the server can return results from the existing index. Index-job cancellation and post-write index synchronization are best effort rather than transactional guarantees.

_Full upstream README: https://allmcps.com/mcp/disco-trooper-apple-notes-mcp/readme_