SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI productivitymcp-apple-notes

mcp-apple-notes

Local semantic search and RAG over Apple Notes with on-device embeddings, full CRUD, folder management and fuzzy title matching.

Open website

About this tool

Purpose

mcp-apple-notes is a Model Context Protocol (MCP) server for implementing semantic search and RAG (Retrieval-Augmented Generation) on Apple Notes. It is suitable for any MCP-compatible client, such as Claude Desktop, Cursor, Windsurf, Cline, etc.

Main Capabilities

  • Semantic search: Uses the all-MiniLM-L6-v2 on-device embedding model to perform semantic retrieval on Apple Notes.
  • Full-text search: Provides full-text search capabilities.
  • Folder support: Can list folders, browse by folder, and filter by folder during search.
  • Vector storage: Uses LanceDB to store vectors.
  • Native integration: Integrates natively with Apple Notes through JXA (Apple's official JavaScript for Automation scripting bridge).
  • Local execution: Runs entirely locally, with no API key required.
  • Read-only mode: Optional read-only mode for safe exploration.

Usage

There are two installation methods:

  1. Install from source (recommended): Clone the repository locally so you can inspect the source code and understand what is executed on your machine. The prerequisites are Node.js (v18+) or Bun. Then add the server to the MCP client configuration, replacing /path/to/mcp-apple-notes with the path to the cloned repository. Read-only mode can be enabled by setting the environment variable MCP_APPLE_NOTES_READ_ONLY=1.
  2. Quick start via npx: If you prefer zero configuration and trust the published npm package, you can add the configuration directly to the MCP configuration.

After setup is complete, restart the client and ask the AI assistant to "index my notes" to get started.

Configuration instructions for each client:

  • Claude Desktop: Open Settings → Developer → Edit Config, paste the JSON configuration into claude_desktop_config.json, then restart Claude Desktop.
  • Cursor: Add the JSON configuration to ~/.cursor/mcp.json (global) or .cursor/mcp.json in the project root directory.
  • Windsurf: add the JSON configuration to ~/.windsurf/mcp.json.

Available tools and verification

All Apple Notes operations are JXA calls that can be inspected in index.ts. No network requests, no background sync, just local script bridge calls.

In read-only mode, only the following tools are available: index-notes, list-folders, list-notes, search-notes, get-note.

Verbose logging can be enabled to view each JXA call before execution (logged to stderr):

  • CLI flag: add --verbose to the args in the MCP client configuration.
  • Environment variable: suitable for clients that support env.

JXA operation reference: all operations go through Apple's JXA script bridge (Application('Notes')). No direct file system access, no network calls. Delete operations are non-permanent—notes go to "Recently Deleted" and can be recovered within 30 days.

Tool responses are JSON objects using a consistent envelope format:

  • Success: { "ok": true, "data": ... }
  • Error: { "ok": false, "error": { "type": "...", "message": "..." } }

Most note-oriented responses now include a stable Apple Notes id so clients can safely track notes after renaming and moving.

Use cases

Scenarios that require local semantic retrieval, full-text search, browsing or filtering by folder for Apple Notes, and integration with MCP-compatible clients to implement RAG.

Limitations

  • Only supports Apple Notes, must run on a Mac.
  • Requires Node.js (v18+) or Bun.
  • Read-only mode disables all write operations.
  • Deleted notes go to "Recently Deleted" and can be recovered within 30 days.
  • The specific available tools and configuration details are subject to the repository documentation; other features and pricing not described in the materials are not provided at this time.

Security and transparency

Because this server interacts with private Apple Notes, it is designed with absolute transparency as the goal, running 100% locally on the Mac. No cloud, no telemetry, no API keys, datadoes not leave the machine. Uses Apple's official JXA script bridge. Embeddings run locally on-device via @huggingface/transformers using the all-MiniLM-L6-v2 model. You are encouraged to read every line of code (especially index.ts) before touching your notes. GitHub releases include SHA-256 checksums so you can verify downloaded artifacts.

Community and support

There are dedicated channels for bug reports, ideas, questions, and showcases: submit bugs as issues; start discussions for feature ideas in Ideas; ask for setup or integration help in Q&A; share interesting projects you built with it in Show and tell; follow Announcements for updates. PRs are welcome; for non-trivial changes, please open an issue or discussion first to align on direction.

Acknowledgments

Initially based on RafalWilinski/mcp-apple-notes.

Related tools

Browse category