de en es ja ko ru zh

mcp-apple-notes

Name: mcp-apple-notes
Author: Dan8Oren

by Dan8Oren

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

MCP Apple Notes

mcp-apple-notes MCP server

Сервер Model Context Protocol (MCP), который обеспечивает семантический поиск и RAG (генерацию с дополненной выборкой) по вашим заметкам Apple Notes. Работает с любым клиентом, поддерживающим MCP — Claude Desktop, Cursor, Windsurf, Cline и другими.

Демонстрация MCP Apple Notes

Возможности

🔍 Семантический поиск по Apple Notes с использованием локальной модели эмбеддингов all-MiniLM-L6-v2
📝 Возможности полнотекстового поиска
📂 Поддержка папок — список папок, просмотр по папкам, фильтрация поиска по папке
📊 Векторное хранилище на базе LanceDB
🤖 Работает с любым MCP-совместимым клиентом (Claude, Cursor, Windsurf, Cline и т.д.)
🍎 Нативная интеграция с Apple Notes через JXA
🔒 Опциональный режим только для чтения для безопасного изучения
🏃♂️ Полностью локальное выполнение — ключи API не нужны

Related MCP server: MCP Apple Notes

Безопасность и прозрачность

Поскольку этот сервер взаимодействует с вашими личными заметками Apple Notes, он разработан с учетом абсолютной прозрачности. Он работает на 100% локально на вашем Mac.

Никакого облака, никакой телеметрии — нет ключей API, данные не покидают ваш компьютер.
Нативный Apple JXA — использует официальный мост сценариев Apple JavaScript for Automation.
Эмбеддинги на устройстве — модель all-MiniLM-L6-v2 работает локально через @huggingface/transformers.
Проверяемость — настоятельно рекомендуется прочитать каждую строку кода (особенно index.ts), прежде чем он получит доступ к вашим заметкам.
Релизы на GitHub включают контрольные суммы SHA-256, чтобы вы могли проверить загруженные артефакты.

Установка и настройка

Выберите метод установки, который подходит для вашего рабочего процесса.

Метод 1: Установка из исходного кода (рекомендуется)

Клонируя репозиторий локально, вы можете изучить исходный код и точно знать, что выполняется на вашем компьютере.

Предварительные требования: Node.js (v18+) или Bun

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && bun install

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

Использование NPM:

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && npm install

Затем добавьте сервер в конфигурацию вашего MCP-клиента. Замените /path/to/mcp-apple-notes на путь, по которому вы клонировали репозиторий:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

Совет: Хотите попробовать без риска? Включите режим только для чтения, чтобы заблокировать все операции записи во время изучения.
"env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }

Метод 2: Быстрый старт через npx

Если вы предпочитаете подход без настройки и доверяете опубликованному пакету npm, вы можете просто добавить это непосредственно в свою конфигурацию MCP:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

После настройки перезапустите клиент и попросите своего ИИ-ассистента "index my notes" (проиндексировать мои заметки), чтобы начать.

Инструкции для конкретных клиентов

Откройте Settings → Developer → Edit Config
Вставьте выбранную JSON-конфигурацию в claude_desktop_config.json
Перезапустите Claude Desktop

Логи:

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log

# npm version:
claude mcp add apple-notes npx -- -y @dan8oren/mcp-apple-notes
# or from source:
claude mcp add apple-notes npx -- tsx /path/to/mcp-apple-notes/index.ts

Добавьте JSON-конфигурацию в ~/.cursor/mcp.json (глобально) или .cursor/mcp.json в корне вашего проекта.

Добавьте JSON-конфигурацию в ~/.windsurf/mcp.json.

Доступные инструменты

Инструмент	Описание
`index-notes`	Индексация всех заметок для семантического поиска. Запустите это первым
`list-folders`	Список всех папок Apple Notes с полными путями и количеством заметок
`list-notes`	Список заметок с метаданными. Опциональный фильтр `path` и флаг `includeContent`
`search-notes`	Семантический + полнотекстовый поиск с опциональным фильтром пути и лимитом
`get-note`	Получение полного содержимого по `noteId` или заголовку. Возвращает варианты при неоднозначности
`create-note`	Создание новой заметки с содержимым в формате markdown, опционально в папке
`edit-note`	Редактирование заголовка и/или содержимого (markdown) существующей заметки
`append-to-note`	Добавление содержимого в формате markdown в существующую заметку
`move-note`	Перемещение заметки в другую папку
`delete-note`	Удаление заметки (перемещает в "Недавно удаленные")

Проверка перед доверием

Каждая операция с Apple Notes — это вызов JXA, который вы можете изучить в index.ts. Никаких сетевых запросов, никакой фоновой синхронизации — только локальные вызовы моста сценариев.

Режим только для чтения

Нужна страховка? Включите режим только для чтения, чтобы заблокировать все операции записи — будут доступны только инструменты поиска, списка и чтения:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }
    }
  }
}

Когда этот режим включен, доступны только следующие инструменты: index-notes, list-folders, list-notes, search-notes, get-note.

Подробный режим (Verbose)

Включите подробное логирование, чтобы видеть каждый вызов JXA перед его выполнением (записывается в stderr):

Флаг CLI — добавьте --verbose в аргументы конфигурации вашего MCP-клиента:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["--verbose", "-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

Переменная окружения — для клиентов, поддерживающих env:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_VERBOSE": "1" }
    }
  }
}

Справочник операций JXA

Операция	Тип	Что делает
`getNotes`	Чтение	Список всех заметок (id, заголовок, путь к папке)
`getFolders`	Чтение	Список всех папок с путями и количеством заметок
`getNotesByPath`	Чтение	Получение заметок в конкретной папке
`getNoteDetailsById`	Чтение	Получение полного содержимого одной заметки по ID
`createNote`	Запись	Создание новой заметки с заголовком и содержимым
`appendToNote`	Запись	Добавление HTML-содержимого в существующую заметку
`editNote`	Запись	Обновление заголовка и/или содержимого заметки
`moveNote`	Запись	Перемещение заметки в другую папку
`deleteNote`	Деструктивная	Перемещение заметки в "Недавно удаленные"

Все операции проходят через мост сценариев Apple JXA (Application('Notes')). Нет прямого доступа к файловой системе, нет сетевых вызовов. Операция delete не является окончательной — заметки попадают в "Недавно удаленные" и могут быть восстановлены в течение 30 дней.

Формат ответа

Ответы инструментов представляют собой JSON-объекты в согласованном конверте:

Успех: { "ok": true, "data": ... }
Ошибка: { "ok": false, "error": { "type": "...", "message": "..." } }

Большинство ответов, связанных с заметками, теперь включают стабильный id Apple Notes, чтобы клиенты могли безопасно отслеживать заметки при переименовании и перемещении.

Благодарности

Изначально основано на RafalWilinski/mcp-apple-notes.

Available Tools

10 tools

append-to-noteB

Append content to the end of an existing Apple Note. Identify note by noteId or title.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional folder path to disambiguate duplicate titles
`title`	No	Title of the note to append to
`noteId`	No	Apple Notes ID. If provided, skips title resolution.
`content`	Yes	Content in markdown format to append to the end of the note

TDQS

B3.3/5.0

Behavior2/5

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

No annotations provided, and the description fails to disclose behaviors such as side effects (e.g., saving the note), required permissions, error states (e.g., if note not found), or any constraints like size limits.

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?

The description is concise (one sentence) and directly addresses the core action, but lacks any structured breakdown (e.g., bullet points) that could improve readability.

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?

Given the complexity of 4 parameters and no output schema, the description omits important context such as the return value (success/failure), error handling, and whether the appending is immediate or requires further action.

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 coverage is 100% and the description mostly repeats the existing schema comments (e.g., 'Optional folder path to disambiguate duplicate titles'), adding no significant new meaning beyond the structured data.

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?

The description clearly states the action (append content), the resource (existing Apple Note), and how to identify it (by noteId or title). It effectively distinguishes from siblings like edit-note or create-note.

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 the tool is for appending content to an existing note, but does not explicitly state when to use it versus alternatives like edit-note or search-notes.

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

create-noteA

Create a new Apple Note with a title and markdown content. Optionally place it in a folder path.

ParametersJSON Schema

Name	Required	Description
`title`	Yes
`folder`	No	Optional folder path to create the note in (e.g. iCloud/Work/Projects). Use list-folders to get available paths.
`content`	Yes	Note content in markdown format

TDQS

A3.5/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 full burden for behavioral disclosure. It does not mention error behaviors, overwrite policies, character limits, or markdown restrictions, leaving significant gaps for an AI agent.

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?

The description is a single sentence with no wasted words. It conveys the essential purpose efficiently.

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?

Given the tool's simplicity and lack of output schema, the description is minimally viable but lacks details about error conditions, folder existence, or fallback behavior. It does not leverage sibling tools for contextual guidance.

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 coverage is 67% (two of three parameters have descriptions). The description adds context by naming 'title and markdown content' and giving a folder path example, but does not substantially enhance understanding beyond the schema for the title parameter.

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?

The description clearly states the verb 'Create', resource 'Apple Note', and key aspects: title, markdown content, and optional folder placement. It effectively distinguishes from sibling tools like edit-note or delete-note.

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 mentions optional folder placement and references list-folders for paths, but does not explicitly state when to use this tool versus alternatives (e.g., append-to-note or edit-note). No when-not-to-use guidance is provided.

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

delete-noteA

Delete an Apple Note (moves to Recently Deleted). Identify note by noteId or title.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional folder path to disambiguate duplicate titles
`title`	No	Title of the note to delete
`noteId`	No	Apple Notes ID. If provided, skips title resolution.

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and discloses the key behavioral trait (soft delete to Recently Deleted) and the mechanism (direct resolution with noteId). It does not cover effects of missing identifiers or permissions, but the core behavior is explained.

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?

The description is a single, well-structured sentence conveying purpose, behavioral detail, and identification options without any extraneous words.

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 simple delete operation with three optional parameters and no output schema, the description adequately covers purpose, behavior, and identification; it lacks details on error handling or ambiguous matches but is largely complete.

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?

The input schema already has 100% description coverage, so the description adds minimal extra meaning beyond summarizing the two identification paths; this meets the baseline for parameter semantics.

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?

The description clearly states the action ('Delete an Apple Note') with specific behavioral detail (moves to Recently Deleted) and identification methods (noteId or title), distinguishing it from sibling tools which perform other operations.

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

Usage Guidelines4/5

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

While not explicitly contrasting with alternatives, the description implies usage scenarios by offering two identification methods; it provides adequate direction for a single-purpose delete tool without needing to exclude other tools.

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

edit-noteA

Edit an existing Apple Note's title and/or content. Identify note by noteId or current title.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional folder path to disambiguate duplicate titles
`title`	No	Current title of the note to edit
`noteId`	No	Apple Notes ID. If provided, skips title resolution.
`newTitle`	No	New title (optional)
`newContent`	No	New content in markdown format (optional, replaces entire content)

TDQS

A3.7/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It mentions identification methods but does not disclose that newContent replaces entire content or describe error handling. The behavioral impact is partially covered but not comprehensively.

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?

Single sentence with no wasted words. The description is concise and front-loaded with the action and key identification method.

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?

Although minimal, the description covers the basic purpose and identification. However, it omits critical details like replacement behavior of newContent, error handling, and results, which would be expected given no output 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 has 100% parameter description coverage. The description adds a high-level summary of identification and edit actions but does not provide significant new semantics beyond the schema.

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?

The description clearly states the tool edits an existing Apple Note's title and/or content, and identifies the note by noteId or current title. This distinctly separates it from sibling tools like create-note or delete-note.

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 use for editing but provides no explicit guidance on when to choose this tool over siblings like append-to-note or when not to use it. No prerequisites or exclusions are mentioned.

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

get-noteA

Get a note's full content and details by noteId or title. Optionally scope by folder path. If the title is ambiguous, returns a list of matching candidates — retry with noteId or path to disambiguate.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional folder path to disambiguate duplicate titles
`title`	No
`noteId`	No	Apple Notes ID. If provided, skips title resolution.

TDQS

A4.2/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It discloses the disambiguation behavior (returns candidates for ambiguous titles) and that noteId skips resolution. However, it does not describe behavior when no parameters are given, error handling, or return format details.

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?

The description is two sentences long, front-loaded with the primary purpose, and contains no superfluous words. Every sentence contributes essential guidance.

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?

Given the tool's moderate complexity (3 optional parameters, no output schema), the description covers core functionality and disambiguation. However, it omits default behavior when no parameters are provided, which could leave agents uncertain.

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 schema covers two of three parameters with descriptions (path, noteId). The description adds value by explaining the title parameter's role in identification and the disambiguation mechanism, which is not present in the schema's empty title description.

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?

The description clearly states 'Get a note's full content and details' using a specific verb and resource. It identifies two identification methods (noteId or title) and distinguishes from sibling tools like create-note, delete-note, etc., which serve different purposes.

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

Usage Guidelines4/5

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

The description provides clear usage context: retrieves note content by noteId or title, with optional folder path for disambiguation. It hints at when to retry with noteId or path if title is ambiguous, but lacks explicit exclusions or alternatives to other sibling tools.

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

index-notesA

Index all Apple Notes for semantic search. Run this first — takes seconds to minutes depending on note count.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior2/5

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

Without annotations, the description must disclose behavioral traits. It only mentions time duration, but does not state if the operation is read-only or has side effects (e.g., creating a database), or any authorization requirements. The safety profile is unclear.

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?

Two sentences, front-loaded with the verb and resource, and every word earns its place. No wasted text.

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 tool with no output schema, the description is nearly complete. It could mention that search-notes depends on this index, but given the simplicity, it's adequate.

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 has zero parameters, so the schema covers all. The description adds value by explaining the purpose and timing, which is consistent with the baseline of 4 for no parameters.

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?

The description clearly states the action 'Index all Apple Notes' with a specific purpose 'for semantic search', and distinguishes from sibling tools by positioning it as a preliminary step ('Run this first').

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

Usage Guidelines4/5

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

The description gives clear usage guidance: 'Run this first' and provides a time estimate. It does not explicitly exclude any scenarios, but with no alternative indexing tools among siblings, the context is sufficient.

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

list-foldersA

List all Apple Notes folders with full paths and note counts

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description is the sole source of behavioral info. It adequately states the tool is a read-only list operation, but it does not disclose potential limitations, authentication needs, or any other behaviors beyond the obvious.

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, concise sentence that front-loads the action and output. No unnecessary words or structures.

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?

Given the simple nature (no parameters, no output schema), the description provides essential info: what it lists and what is included. Missing usage context slightly lowers completeness.

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 has zero parameters and schema description coverage is 100%, so the baseline is 4. The description does not need to add param info and correctly omits it.

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?

The description clearly states the action ('list') and resource ('all Apple Notes folders'), including what is returned ('full paths and note counts'). This distinctively separates it from sibling tools like list-notes and search-notes.

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 guidance is provided on when to use this tool versus alternatives. The description simply states what it does without any contextual usage advice or exclusion criteria.

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

list-notesA

List Apple Notes with title, path, and timestamps. Optionally filter by folder path and include note content.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Optional folder path to filter notes (e.g. iCloud/Work/Projects). Use list-folders to get available paths.
`includeContent`	No	If true, include note content in the response (default: false)

TDQS

A4.1/5.0

Behavior3/5

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

No annotations are provided, so the description must fully disclose behavior. It notes basic output fields but omits details on pagination, ordering, or rate limits.

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, concise sentence that front-loads the main action and optional features, with no extraneous words.

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?

Given no output schema and multiple sibling tools, the description should mention ordering, pagination, or when to use list-notes vs search-notes; it lacks these details.

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?

Schema description coverage is 100%, but the description adds context by listing return fields (title, path, timestamps) and clarifying the path parameter's purpose beyond the schema.

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?

The description clearly states the tool lists Apple Notes with specific attributes (title, path, timestamps), distinguishing it from sibling tools like get-note (single note) and search-notes (searching).

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

Usage Guidelines4/5

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

The description mentions optional filtering by folder path and references list-folders for available paths, but does not explicitly contrast with alternatives like search-notes for advanced queries.

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

move-noteA

Move a note to a different folder. Identify note by noteId or title. Use list-folders to get available paths.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional current folder path to disambiguate duplicate titles
`title`	No	Title of the note to move
`noteId`	No	Apple Notes ID. If provided, skips title resolution.
`targetPath`	Yes	Full folder path to move the note to (e.g. iCloud/Work/Projects)

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description bears the full burden. It implies mutation (moving a note) and describes identification methods, but lacks details on side effects, error conditions, or behavior for ambiguous titles.

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?

Two sentences: first states core purpose, second covers identification and a helpful hint. No wasted words, front-loaded.

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?

Given 4 parameters and no output schema, the description covers identification and references list-folders for paths. It could mention what happens if targetPath doesn't exist, but overall adequate for a move operation.

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?

Schema coverage is 100%, baseline 3. The description adds value by explaining the relationship between noteId and title as alternative identifiers, and notes the path parameter's role in disambiguation.

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?

The description clearly states the verb 'move' and the resource 'note' with destination 'folder', distinguishing it from sibling tools like create-note, delete-note, etc.

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

Usage Guidelines4/5

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

The description explains how to identify the note (by noteId or title) and suggests using list-folders to get available paths, providing clear context for usage. However, it doesn't explicitly state when not to use this tool or alternatives.

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

search-notesB

Semantic and full-text search over notes. Optionally filter by folder path.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional: filter results to a specific folder path (e.g. iCloud/Work)
`limit`	No	Max results to return (default: 50)
`query`	Yes

TDQS

B3.4/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only mentions search type (semantic/full-text) and an optional filter, but omits details like whether this is read-only, how results are ordered, pagination behavior, or content indexing status. This is insufficient for safe invocation.

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?

Two sentences, front-loaded with the core action and one key option. Every word contributes meaning. No redundancy or excess.

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?

Given the lack of output schema and annotations, the description is too sparse. It does not explain return format, what 'semantic' search entails, or potential limitations. For a search tool with multiple siblings, more context is needed for effective selection and use.

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 67% (query lacks description). The description adds 'Optionally filter by folder path' which echoes the schema. It does not clarify the query parameter's syntax or semantics, nor does it explain limit behavior beyond the schema's default. Overall minimal added value beyond the schema.

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?

The description 'Semantic and full-text search over notes' clearly identifies the tool's action (search) and resource (notes), and the optional folder path filter adds specificity. It effectively distinguishes from sibling tools like list-notes and get-note by emphasizing content-based 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 states the tool's capabilities but does not explicitly guide when to use it versus alternatives. No mention of when-not-to-use or suggestions for other tools like list-notes for browsing or get-note for a specific note.

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.

10 tool updatesv1.0.1Apr 27, 2026
- First observedappend-to-note
- First observedcreate-note
- First observeddelete-note
- First observededit-note
- First observedget-note
- First observedindex-notes
- First observedlist-folders
- First observedlist-notes
- First observedmove-note
- First observedsearch-notes

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

A4/5.0

Scored 2026-09-09 18:50 across 10 tools

Disambiguation5/5

Each tool targets a distinct action and resource: indexing, listing folders, listing notes, searching, getting, creating, editing, appending, moving, and deleting. While list-notes with content and get-note overlap slightly, the descriptions clearly differentiate listing summaries versus fetching full details.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern: index-notes, list-folders, search-notes, get-note, create-note, etc. This makes the tool set predictable and easy to navigate for an agent.

Tool Count5/5

With 10 tools, the server is well-scoped for Apple Notes management. Each tool covers a necessary operation without bloat, and the count feels appropriate for the domain.

Completeness5/5

The surface covers the full note lifecycle: index, list, search, get, create, edit, append, move, and delete. Folder listing supports scoping operations, leaving no obvious dead ends for common workflows.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

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
cortexpad A
com.cortexpad
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Note Taking Knowledge & Memory
162
ainote BOAuth
io.github.seunghan91
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Note Taking Developer Tools Knowledge & Memory
3
TaprootOAuth
com.taproothq
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Knowledge & Memory Note Taking
2

Related MCP Servers

Apple Notes MCP Server
Note Taking Autonomous Agents
Siddhant-K-code
A
license
D
quality
B
maintenance
Enables interaction with Apple Notes via natural language, supporting note creation, search, and retrieval with iCloud integration for seamless note management.
Updated a month ago (2026-09-10 01:01 UTC)
3
20 npm
25
MIT
MCP Apple Notes
Note Taking Search Vector Databases
Dingzeefs
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables semantic search and retrieval of Apple Notes content, allowing AI assistants to access, search, and create notes using on-device embeddings.
Updated 2 years ago (2025-03-03 20:02 UTC)
4,781 npm
2
MIT
Apple Notes MCP Server
Note Taking OS Automation App Automation
arslankhanali
F
license
A
quality
D
maintenance
Enables interaction with Apple Notes on macOS through AppleScript, allowing users to list, search, read, create, update, and delete notes across accounts and folders.
Updated 10 months ago (2025-12-03 01:22 UTC)
7
1
-
Apple Notes MCP
Note Taking OS Automation App Automation
renatoaraujo
F
license
A
quality
D
maintenance
A local-only server that enables AI agents to create, read, search, and organize Apple Notes directly on macOS. It supports folder management, note formatting, and checklists using native automation to ensure data remains private and local.
Updated 7 months ago (2026-03-24 09:21 UTC)
24
10 npm
-