Apple Notes MCP

🚀 Apple Notes Model Context Protocol Server (Claude Desktop)

Read your local Apple Notes database and make it available to Claude Desktop.

Now Claude can search your most forgotten notes and learn more about you.

🚀 Quick Start

Install the Server

It is recommended to use uv to install the server locally for Claude to use.

uvx apple-notes-mcp

OR

uv pip install apple-notes-mcp

Add the configuration as described below.

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Note: You may need to use the direct path to uv. Run which uv to find the path.

Configuration for the development/unpublished server

"mcpServers": {
  "apple-notes-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "{project_dir}",
      "run",
      "apple-notes-mcp"
    ]
  }
}

Configuration for the published server

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

✨ Features

Resources

The server implements the ability to read and write Apple Notes.

Tools

The server provides several prompts:

• get-all-notes: Get all notes.
• read-note: Get the full content of a specific note.
• search-notes: Search in notes.

📦 Installation

Mac OS Disk Permissions

You need to grant the server full disk access. This is because the Apple Notes SQLite database is located deep in the MacOS file system.

If this bothers you, or if you want to start adding or appending to Apple Notes, you might consider using an AppleScript solution.

💻 Usage Examples

Build and Publish

To prepare for distribution:

1. Sync dependencies and update the lock file:

uv sync

2. Build the release:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You need to set your PyPI credentials via environment variables or command-line flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since the MCP server runs through stdio, debugging can be challenging. For the best debugging experience, we highly recommend using MCP Inspector.

You can start the MCP Inspector with the following command:

npx @modelcontextprotocol/inspector uv --directory {project_dir} run apple-notes-mcp

After starting, the Inspector will display a URL that you can access in your browser to start debugging.

📚 Documentation

Missing Features

• Unhandled encrypted notes (ZISPASSWORDPROTECTED)
• No support for filtering pinned notes
• Unhandled cloud synchronization status
• Missing attachment content retrieval
• No support for checking list status (ZHASCHECKLIST)
• Unable to create or edit notes

📄 License

This project is released under the MIT License. For more details, see the LICENSE file.

Source Code

The source code is available on GitHub.

Contributing to the Project

Send your ideas and feedback to my Bluesky, or submit them by opening an issue.