使用说明

Apple Notes MCP服务器（Go实现）

用于Apple Notes的MCP（模型上下文协议）服务器的独立Go实现，提供MCP协议集成和CLI工具功能。

特性

MCP服务器模式：与Claude Desktop和其他MCP客户端集成
- 14工具：完整的笔记生命周期、文件夹管理、高级搜索、附件和导出
- 4资源类型：通过URI直接访问笔记（note:///，notes:///recent, notes:///search/{query}，notes:///folder/｛文件夹｝）
- 6提示模板：用于常见笔记操作的一键式工作流（每日回顾、每周总结、会议准备、行动项、笔记清理、快速笔记）
- 元数据：所有注释都包括创建/修改日期、文件夹、共享状态和ID
CLI工具模式：用于管理Apple Notes的命令行界面
三层体系结构：协议、业务逻辑和操作系统交互之间的清晰分离
可配置超时：对大型Notes数据库的环境变量支持
结果限制：自动限制搜索结果以防止超时

需求

转到1.21或更高版本
安装了Apple Notes的macOS
通过AppleScript访问Apple Notes的系统权限

安装

使用Homebrew（推荐）

brew install harperreed/tap/notes-mcp

使用Make

make build        # Build the binary
make install      # Install to /usr/local/bin

直接使用Go

go build -o notes-mcp .

用法

MCP服务器模式

作为MCP服务器运行以与Claude Desktop集成：

notes-mcp mcp

CLI工具模式

用作命令行工具：

核心笔记操作

# Create a note
notes-mcp create "Meeting Notes" "Discussed Q4 roadmap" --tags=work,meeting

# Get note content with full metadata
notes-mcp get "Meeting Notes"

# Update a note
notes-mcp update "Meeting Notes" "Updated Q4 roadmap with new timeline"

# Delete a note
notes-mcp delete "Old Note"

搜索和发现

# Basic search by title
notes-mcp search "meeting"

# Advanced search in note body
notes-mcp search-advanced "roadmap" --search-in=body

# Search with folder filter
notes-mcp search-advanced "meeting" --folder="Work"

# Search with date range
notes-mcp search-advanced "project" --date-from="2024-01-01" --date-to="2024-12-31"

# Combine all filters
notes-mcp search-advanced "roadmap" --search-in=both --folder="Work" --date-from="2024-01-01"

文件夹管理

# List all folders
notes-mcp folders

# Create a folder at root level
notes-mcp create-folder "Work Projects"

# Create a nested folder
notes-mcp create-folder "Active Projects" --parent="Work"

# Move a note to different folder
notes-mcp move-note "Meeting Notes" "Archive"

# Get folder hierarchy with note counts
notes-mcp folder-hierarchy

附件

# List attachments in a note
notes-mcp attachments "Trip Photos"

# Get attachment content (saves to file or stdout)
notes-mcp get-attachment "x-coredata://..." --output="photo.jpg"

# Get attachment with size limit
notes-mcp get-attachment "x-coredata://..." --max-size=5

出口

# Export note as markdown
notes-mcp export-markdown "Design Doc"

# Export note as plain text
notes-mcp export-text "Design Doc"

Claude桌面集成

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "apple-notes": {
      "command": "notes-mcp",
      "args": ["mcp"],
      "env": {
        "NOTES_MCP_TIMEOUT": "60"
      }
    }
  }
}

配置选项

备注_MCP_TIMEOUT：操作的可选超时时间（秒）（默认值：30）。如果您有一个大型Notes数据库，并且在搜索过程中遇到超时，请增加。
搜索结果自动限制为100条注释，以防止大型结果集超时。

MCP工具

服务器为Claude提供了14个与Apple Notes交互的工具：

核心笔记操作

create_note -使用标题、内容和可选标签创建新笔记
```
{
  "title": "Meeting Notes",
  "content": "Discussed Q4 roadmap",
  "tags": "work,meeting"
}
```
返回完整的笔记元数据，包括创建日期、文件夹和ID。
get_note_content -使用元数据检索笔记的完整HTML内容
```
{
  "title": "Meeting Notes"
}
```
返回带有creation_date、modification_date、文件夹、共享状态和ID的注释。

update_note -更新现有注释的内容

{
  "title": "Meeting Notes",
  "content": "Updated with action items"
}

delete_note -按标题删除注释
```
{
  "title": "Old Note"
}
```

搜索和发现

search_notes -按标题进行基本搜索（限制为100个结果）
```
{
  "query": "meeting"
}
```
返回包含完整元数据的笔记数组。
search_notes_advanced -使用正文内容、文件夹和日期过滤器进行高级搜索
```
{
  "query": "roadmap",
  "search_in": "body",
  "folder": "Work",
  "date_from": "2024-01-01",
  "date_to": "2024-12-31"
}
```
- search_in：“title”（默认）、“body”或“both”
- folder：可选-将搜索限制到特定文件夹
- date_from/date_to：可选-按修改日期筛选
- 性能说明：在大型数据库上，身体搜索可能很慢

文件夹管理

list_folders -列出Apple Notes中的所有文件夹
```
{}
```
创建文件夹 -创建一个具有可选父文件夹的新文件夹
```
{
  "name": "Work Projects",
  "parent_folder": "Work"
}
```
省略 parent_folder 在根级别创建。

move_note -将笔记移动到其他文件夹

{
  "note_title": "Meeting Notes",
  "target_folder": "Archive"
}

get_folder_层次结构 -使用笔记计数获取嵌套文件夹结构
```
{}
```
返回显示所有文件夹、子文件夹和笔记计数的树结构。

附件

get_note_attachments -在注释中列出所有附件
```
{
  "note_title": "Trip Photos"
}
```
返回包含名称、文件路径、创建日期和ID的附件数组。
获取附件内容 -以base64格式检索附件内容
```
{
  "attachment_id": "x-coredata://...",
  "max_size_mb": 10
}
```
默认最大大小为10MB。对于小文件返回base64编码的内容，对于大文件返回错误。

出口

export_note_markdown -将注释内容导出为标记
```
{
  "note_title": "Design Doc"
}
```
将HTML内容转换为markdown格式。
export_note_text -以纯文本形式导出注释内容
```
{
  "note_title": "Design Doc"
}
```
返回不带HTML格式的纯文本。

MCP资源

服务器将笔记作为直接访问的资源公开：

note:///{title} -按标题访问特定注释（例如。， note:///Meeting%20Notes)
notes:///recent -列出20条最近修改的注释
notes:///search/{query} -搜索结果作为资源（例如。， notes:///search/meeting)
notes:///folder/{folder} -在特定文件夹中列出笔记（例如。， notes:///folder/Work)

资源允许Claude直接阅读笔记内容，而无需调用工具，从而更自然地说出“基于我的会议笔记…”之类的话

MCP提示

服务器为常见工作流提供了六个预构建的提示模板：

每日回顾 -复习今天的笔记，包括总结和行动项目
每周总结 -按类别综合每周总结（可选： categories)
会议准备 -使用相关笔记准备会议（要求： topic，可选： attendees)
行动项目 -提取并组织行动项目（必填： search_term，可选： status)
注释清理 -确定要存档或删除的注释（可选： age_threshold_days)
快速笔记 -用于快速捕获笔记的结构化模板（必需： note_type, title)

提示由用户触发，为Claude提供常见音符操作的结构化指令。它们出现在MCP客户端的提示菜单中，可一键访问。

发展

快速开始使用Make

make help         # Show all available commands
make build        # Build the binary
make test         # Run unit tests
make lint         # Run linter
make check        # Run format, lint, and test
make run          # Build and start MCP server
make clean        # Remove build artifacts

运行测试

# Using Make
make test                  # Unit tests only
make test-integration      # Integration tests (requires Apple Notes)
make test-all             # All tests
make test-coverage        # Generate coverage report

# Using Go directly
go test ./...
go test -tags=integration ./...

开发工作流程

make format       # Format code
make lint         # Run linter
make lint-fix     # Auto-fix linting issues
make check        # Full check (format + lint + test)
make pre-commit   # Run all pre-commit hooks

项目结构

notes-mcp/
├── go.mod
├── go.sum
├── main.go                    # CLI entry point with cobra
├── cmd/                       # Subcommand implementations
│   ├── mcp.go                # MCP server subcommand (14 tools + resources + prompts)
│   ├── create.go             # create note subcommand
│   ├── search.go             # search notes subcommand
│   ├── get.go                # get note content subcommand
│   ├── update.go             # update note subcommand
│   ├── delete.go             # delete note subcommand
│   ├── folders.go            # list folders subcommand
│   ├── create_folder.go      # create folder subcommand
│   ├── move_note.go          # move note subcommand
│   ├── folder_hierarchy.go   # get folder hierarchy subcommand
│   ├── search_advanced.go    # advanced search subcommand
│   ├── attachments.go        # list attachments subcommand
│   ├── get_attachment.go     # get attachment content subcommand
│   ├── export_markdown.go    # export as markdown subcommand
│   └── export_text.go        # export as plain text subcommand
├── services/                  # Business logic layer
│   ├── notes.go              # NotesService interface & implementation
│   ├── notes_test.go         # Unit tests with mock executor
│   ├── notes_integration_test.go  # Integration tests
│   ├── applescript.go        # ScriptExecutor interface & implementation
│   ├── applescript_test.go   # Executor unit tests
│   └── errors.go             # Custom error types & detection
├── README.md
└── docs/
    └── plans/
        ├── 2025-11-20-apple-notes-mcp-design.md
        └── 2025-11-20-notes-mcp-enhancements.md

建筑

该实现遵循三层架构：

协议/CLI层：处理MCP协议通信和CLI接口
服务层：钞票操作的业务逻辑
执行层：AppleScript执行和操作系统交互

看文档/计划/2025-11-20-应用程序注释-mcp-design.md 详细的设计文档。

许可证

待定

使用说明

Apple Notes MCP服务器（Go实现）

特性

需求

安装

使用Homebrew（推荐）

使用Make

直接使用Go

用法

MCP服务器模式

CLI工具模式

核心笔记操作

搜索和发现

文件夹管理

附件

出口

Claude桌面集成

配置选项

MCP工具

核心笔记操作

搜索和发现

文件夹管理

附件

出口

MCP资源

MCP提示

发展

快速开始使用Make

运行测试

开发工作流程

项目结构

建筑

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

Flomo笔记服务

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器