apple-notes-mcp

Apple Notes MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to read, create, search, and manage notes in Apple Notes on macOS.

What is This?

This server acts as a bridge between AI assistants and Apple Notes. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Save this conversation as a note called 'Meeting Summary'"
• "Find all my notes about the project deadline"
• "Read my shopping list note"
• "Move my draft notes to the Archive folder"
• "What notes do I have in my Work folder?"

The AI assistant communicates with this server, which then uses AppleScript to interact with the Notes app on your Mac. All data stays local on your machine.

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-notes-mcp MCP server so you can help me manage my Apple Notes

Claude will handle the installation and configuration automatically.

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-notes-mcp
/plugin install apple-notes

This method also installs a skill that teaches Claude when and how to use Apple Notes effectively.

Manual Installation

1. Install the server:

npm install -g github:sweetrb/apple-notes-mcp

2. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

3. Restart Claude Desktop and start using natural language:

"Create a note called 'Ideas' with my brainstorming thoughts"

On first use, macOS will ask for permission to automate Notes.app. Click "OK" to allow.

Requirements

• macOS - Apple Notes and AppleScript are macOS-only
• Node.js 20+ - Required for the MCP server
• Apple Notes - Must have at least one account configured (iCloud, Gmail, etc.)

Features

Feature	Description
Create Notes	Create notes with titles, content, and optional organization
Search Notes	Find notes by title or search within note content
Read Notes	Retrieve note content and metadata
Update Notes	Modify existing notes (title and/or content)
Delete Notes	Remove notes (moves to Recently Deleted)
Move Notes	Organize notes into folders
Folder Management	Create, list, and delete folders
Multi-Account	Work with iCloud, Gmail, Exchange, or any configured account
Batch Operations	Delete or move multiple notes at once
Checklist State	Read checklist done/undone state directly from the Notes database
Export	Export all notes as JSON or get individual notes as Markdown
Attachments	List attachments in notes
Sync Awareness	Detect iCloud sync in progress, warn about incomplete results
Collaboration	Detect shared notes, warn before modifying
Diagnostics	Health check, sync status, and statistics tools

---

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Note Operations

create-note

Creates a new note in Apple Notes.

Parameter	Type	Required	Description
title	string	Yes	The title of the note. Automatically prepended as <h1> — do NOT include the title in content
content	string	Yes	The body content of the note (do not repeat the title here)
tags	string[]	No	Tags for organization (stored in metadata)
format	string	No	Content format: "plaintext" (default) or "html". In both formats, the title is automatically prepended as <h1>. In plaintext mode, newlines become <br>, tabs become <br>, and backslashes are preserved as HTML entities

Example:

{
  "title": "Meeting Notes",
  "content": "Discussed Q4 roadmap and budget allocation",
  "tags": ["work", "meetings"]
}

Example - HTML formatting:

{
  "title": "Status Report",
  "content": "<h2>Summary</h2><p>All tasks <b>on track</b>.</p><ul><li>Feature A: complete</li><li>Feature B: in progress</li></ul>",
  "format": "html"
}