Skip to main content
Glama
Apple Notes MCP

Apple Notes MCP

by fattoliu

中文 | English

Apple Notes MCP

A TypeScript MCP (Model Context Protocol) server that lets AI assistants (Claude, etc.) save well-organized technical articles to Apple Notes and local Markdown files simultaneously.

Features

  • Markdown input — AI writes Markdown, the server converts it to Apple Notes rich HTML automatically

  • Dual write — saves to both ~/Documents/notes/[category]/[title].md and Apple Notes at the same time

  • Auto folder creation — if the target folder doesn't exist, it's created on the fly

  • Article metadata — automatically appends save time, tags, and source to each note

  • Provider pattern — clean extensible architecture; adding new targets (Yuque, Feishu, etc.) requires zero changes to existing code

  • Configurable via env vars — notes root dir and enabled providers are all configurable

Related MCP server: simplenote-mcp

Tools

Tool

Description

save_article

Save a Markdown article to all enabled providers

list_articles

List articles in a folder (or all folders)

search_articles

Full-text search across all notes

get_article

Read a note by ID

list_folders

List all Apple Notes folders

Architecture

AI Client (Claude Desktop / Claude Code)
        │  stdio (MCP protocol)
        ▼
MCP Server (index.ts)
        │
        ▼
save-article.ts  ← orchestration only, 9 lines
        │
        ├──▶ LocalMarkdownProvider  →  ~/Documents/notes/[category]/[title].md
        │
        └──▶ AppleNotesProvider     →  osascript → Apple Notes App

Each provider implements the NoteProvider interface:

export interface NoteProvider {
  readonly name: string;
  save(article: Article): Promise<ProviderResult>;
}

Adding a new provider (e.g. Yuque) only requires:

  1. Create src/providers/yuque.ts implementing NoteProvider

  2. Register it in src/providers/index.ts

  3. Add any required env vars (e.g. YUQUE_TOKEN)

No existing code needs to change.

Requirements

  • macOS (Apple Notes via AppleScript)

  • Node.js v18+

  • iCloud account with Notes sync enabled

Installation

git clone https://github.com/fattoliu/apple-notes-mcp.git
cd apple-notes-mcp
npm install
npm run build

Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json) or project .mcp.json:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": ["/path/to/apple-notes-mcp/dist/index.js"],
      "env": {
        "NOTES_ROOT": "/Users/yourname/Documents/notes",
        "ENABLE_LOCAL_MD": "true",
        "ENABLE_APPLE_NOTES": "true"
      }
    }
  }
}

Environment Variables

Variable

Description

Default

NOTES_ROOT

Root directory for local Markdown files

~/Documents/notes

ENABLE_LOCAL_MD

Enable local Markdown saving

true

ENABLE_APPLE_NOTES

Enable Apple Notes saving

true

Usage

After setup, just tell Claude:

Summarize our conversation about X into a technical article, save it to the "TypeScript" category with tags ts and generics.

Claude will call save_article and both targets are written automatically.

macOS Permissions

On first run, macOS will prompt you to allow access to Notes. Click Allow.

If the prompt doesn't appear, go to: System Settings → Privacy & Security → Automation and grant access manually.

License

MIT

Available Tools

5 tools
get_articleC

读取 Apple Notes 中指定 ID 的笔记内容,返回文章标题和 HTML 内容。

Inputs: note_id (required).

list_articlesA

列出 Apple Notes 中指定文件夹下的所有文章,返回文章标题、ID 和修改时间。不指定文件夹则列出所有文章。

Inputs: category.

list_foldersA

列出 Apple Notes iCloud 账户下的所有文件夹,返回文件夹名称和 ID 列表。

Inputs: no named parameters.

save_articleA

将 AI 整理的技术文章(Markdown 格式)保存到 Apple Notes 备忘录。自动转换 Markdown 为 HTML,在指定文件夹下创建笔记(文件夹不存在时自动创建),并在文章末尾追加保存时间、标签、来源等元数据。

Inputs: title (required), content (required), category (required), tags, +1 more.

search_articlesB

在 Apple Notes 中搜索文章,支持按标题和内容关键词搜索,返回匹配的文章标题、ID 和所在文件夹。

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: listing articles, listing folders, saving, searching, and fetching by ID. The boundaries between list_articles (by folder), search_articles (by keyword), and get_article (by ID) are clear from the descriptions.

    Naming Consistency5/5

    All five tools follow a clean verb_noun snake_case pattern (list_articles, list_folders, save_article, search_articles, get_article). Naming is fully predictable.

    Tool Count5/5

    Five tools is well-scoped for a focused Apple Notes integration covering folder listing, article listing, save, search, and retrieval. No redundant or filler tools.

    Completeness3/5

    The surface covers create, read, list, and search, but lacks update and delete operations for existing notes, which are notable gaps for a notes-management domain. Agents can save new notes but cannot edit or remove them.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI tools to read and optionally write Simplenote notes via local database or API, supporting offline use on macOS.
      369 npm
      33
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to capture, search, update, and delete notes in a local Markdown vault with automatic categorization and tagging, making knowledge management seamless.
      6 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, write, and manage Apple Notes directly via markdown, including listing, fetching, creating, and appending notes.
      -