Which integrations are available for this server?

Enables saving Markdown articles as rich notes in Apple Notes, with automatic conversion from Markdown to HTML, and appends metadata such as save time, tags, and source.

How do I use Apple Notes MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Apple Notes MCP Save the discussion about React state management to the 'React' category with tags state, hooks." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Apple Notes MCP

by fattoliu

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

中文 | 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: Apple Notes MCP Server

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:

Create src/providers/yuque.ts implementing NoteProvider
Register it in src/providers/index.ts
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 内容。

ParametersJSON Schema

Name	Required	Description	Default
`note_id`	Yes	笔记 ID，格式为 Core Data 路径，如 "x-coredata://UUID/ICNote/p1234"

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the return payload (title + HTML) but says nothing about permissions (Apple Notes access), whether a missing ID errors, or whether fetching has side effects. For a zero-annotation read tool, this is thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence that front-loads the verb and resource, then names the return payload. No filler. Slightly high because the return-payload clause is the only extra information and it is genuinely useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with no annotations and no output schema, the description should specify access requirements and failure behavior (e.g., unknown ID). It covers the happy-path contract but leaves an agent without enough context for correct invocation in error or permission scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the note_id schema already explains the Core Data path format thoroughly. The description adds only the implication that note_id is required. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (读取/get) and resource (Apple Notes 中指定 ID 的笔记), plus the return payload (标题和 HTML 内容). It does not explicitly distinguish itself from search_articles or list_articles, the closest siblings, but the specificity of '指定 ID' makes the read-by-id intent clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance. It does not say to use this only when a note_id is already known, nor point to search_articles or list_articles for discovery. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_articlesA

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

ParametersJSON Schema

Name	Required	Description	Default
`category`	No	文件夹名称。不指定则列出所有文件夹中的所有文章。

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

没有提供注解，因此描述需要承担说明负担。它披露了返回字段和默认文件夹行为，这很有帮助，但并未说明分页、结果数量限制或结果是否已排序，对于列表工具而言这是一个缺口。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

两句话，没有冗余，先说范围，再说默认情况。高效，但可作为泛泛而谈的正确性示例。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

对于一个简单的、只有一个可选参数的列表工具来说已经足够完整，它提到了返回字段，因此无需输出架构。只是缺少分页/限制行为。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

架构描述覆盖率为 100%，唯一的参数（category）已在架构中完整记录，因此基线为 3。描述只是重复了默认行为，没有为架构添加格式或命名语义。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

明确说明了动词+资源（列出文章）以及范围（Apple Notes 中某个文件夹下），并指出了返回字段。它隐含地与 get_article/search_articles 区分开来，但并未明确提及任何同级工具。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

通过说明省略文件夹时会列出所有文章，隐含地表达了使用场景，但没有说明何时应优先选择 search_articles 或 get_article，也没有给出任何排除条件。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return shape (folder names and IDs), which matters because no output schema exists, and 'list' implies a read-only operation. However, it says nothing about authentication requirement for the iCloud account or behavior on empty/absent accounts, leaving some behavioral gaps. Since the definition contradicts no annotations, no penalty applies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that states scope first and the return payload second. Every clause earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool with no output schema, the description covers the essentials, including the return contents (names and IDs). It could be more complete by noting the read-only nature and the account/permission prerequisite, but nothing critical to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. There are no parameter semantics to explain, and the schema is fully consistent with a no-argument call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: listing all folders under the Apple Notes iCloud account. It is distinguishable from every sibling (list_articles, save_article, search_articles, get_article), none of which concern folders, though the domain mismatch with the article-oriented siblings is worth noting. It stops just short of 5 because it does not explain the scope boundary (e.g., whether nested/shared folders are included).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the tool for browsing the folder structure, but the description names no alternatives or conditions for when to use it versus other discovery tools. With no parameters there is little ambiguity, but no explicit when/when-not guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_articleA

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

ParametersJSON Schema

Name	Required	Description
`tags`	No	文章标签列表，如 ["TypeScript", "Node.js"]
`title`	Yes	文章标题
`source`	No	文章来源说明，如"Claude 对话整理"
`content`	Yes	文章内容，Markdown 格式。支持标题（#-######）、粗体、斜体、行内代码、代码块、列表、引用块、链接、分割线等。
`category`	Yes	保存到的分类名称，同时作为本地目录名和 Apple Notes 文件夹名。如果不存在会自动创建。

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

无注解，因此描述承担了全部行为披露责任。描述了关键副作用：自动将 Markdown 转换为 HTML、在文件夹不存在时自动创建、并在末尾追加元数据（保存时间、标签、来源）。但未说明所需的权限、错误处理或操作是否可逆。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

单句描述，高效且前置信息丰富，涵盖了核心功能和主要行为特征。没有冗余内容。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

对于一个没有输出 schema 的写入工具，描述基本涵盖了主要行为，但缺少对返回结果、错误情况或可能失败原因的说明。鉴于有 5 个参数且无输出 schema，可以更完整。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema 描述覆盖率为 100%，因此每个参数的含义已在 schema 中清晰定义。描述没有为参数添加额外的语义信息，但也没有矛盾。根据规则，高 schema 覆盖率下基线为 3。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确陈述了动词（保存）、资源（技术文章）以及目标（Apple Notes 备忘录），并具体说明会自动转换 Markdown 为 HTML 并在指定文件夹创建笔记。与同级工具（list_articles、search_articles 等）有清晰区分，因为它是一个写入操作。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

隐含了使用场景：当需要将 AI 整理的 Markdown 文章保存到 Apple Notes 时使用。但没有明确说明何时不使用、与其他同级工具的关系，或调用前的先决条件。属于最低限度的可用指引。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_articlesB

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

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	搜索关键词，会在文章标题和正文中匹配

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not state that this is a read-only operation, whether results are ranked or limited, whether matching is case-sensitive, or any pagination behavior. Only the return fields are mentioned, leaving most behavioral traits undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that front-loads the action, app, and matching scope. No wasted words, though it crams scope, matching fields, and return values into one clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter search tool, the description covers what it does and what it returns, which is adequate. But with no annotations, no output schema, and no mention of read-only nature, result limits, or sibling differentiation, it leaves meaningful gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is only one parameter, so the schema already fully documents the query field. The description adds the detail that matching happens in both 标题 and 正文, which is mildly more than the schema restates, meriting the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (搜索/search), a resource (文章/articles), the target app (Apple Notes), and the matching fields (标题和内容关键词). It is clear what the tool does, though it doesn't explicitly distinguish itself from siblings like list_articles or get_article (which imply retrieval without search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage — search when you have a keyword — but does not state when to use this tool versus list_articles (enumerate all) or get_article (fetch one by ID). No exclusions or alternatives are named, so routing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

5 tool updatesv1.0.0Sep 13, 2026
- First observedget_article
- First observedlist_articles
- First observedlist_folders
- First observedsave_article
- First observedsearch_articles

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-13 12:35 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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

SombraOAuth
so.sombra
AI research library. Save, organise and reuse notes and webpages as clean markdown context.
Note Taking Research & Data Web Scraping
2
notesbridgeOAuth
io.github.IsaiahDupree
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Note Taking App Automation
1
sensefold AOAuth
app.sensefold
Personal context for every AI: search, read, and write back to your private Markdown library.
Knowledge & Memory Note Taking Search
111
Jade NoteOAuth
app.jadenote
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Note Taking Knowledge & Memory
2

Related MCP Servers

MCP Apple Notes
Note Taking RAG Systems Search
gsarti
F
license
Not graded
quality
Not graded
maintenance
Enables AI assistants like Claude to search and reference your Apple Notes using semantic search and RAG capabilities, with fully local execution and no API keys required.
Updated 8 months ago (2026-01-09 00:22 UTC)
2,008 npm
-
Apple Notes MCP Server
Note Taking Knowledge & Memory
RodriguesJohn
A
license
A
quality
D
maintenance
Enables AI assistants to read, create, search, update, and delete Apple Notes through natural language conversation, using JXA to communicate directly with the Notes app.
Updated 6 months ago (2026-03-20 17:57 UTC)
8
2,008 npm
28
MIT
simplenote-mcpofficial
Note Taking Search
Automattic
A
license
Not graded
quality
C
maintenance
Enables AI tools to read and optionally write Simplenote notes via local database or API, supporting offline use on macOS.
Updated 2 months ago (2026-07-27 18:42 UTC)
134 npm
24
MIT
second-brain-mcp
Note Taking Knowledge & Memory
pthieenlong
A
license
Not graded
quality
B
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.
Updated 2 months ago (2026-07-24 02:10 UTC)
2 npm
1
MIT

Apple Notes MCP

Features

Tools

Architecture

Requirements

Installation

Configuration

Environment Variables

Usage

macOS Permissions

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

simplenote-mcpofficial

Appeared in Searches