AI导哈

macOS MCP 服务器

生产就绪的模型上下文协议（MCP）服务器，用于深度集成macOS的笔记、提醒、日历、联系人和消息功能。

  • by zenHeart
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 zenHeart/macos-app-mcp

使用说明

macOS MCP服务器

用于深度macOS集成的生产就绪模型上下文协议（MCP）服务器： 笔记、提醒、日历、联系人和消息。

✨ 特性

  • 🗒️ 备注 -支持分层文件夹的完整CRUD
  • ✅ 提醒事项 -跨多个列表管理任务
  • 📅 日历 -查看、创建和管理事件
  • 👥 联系人 -深度搜索和详细信息检索
  • 💬 沟通 -发送iMessage并发起电话
  • 🛡️ 恢复 -高保真“最近删除”恢复程序和版本回滚
  • 🔒 安全 -用于破坏性操作的安全锁和基于ID的确认

🚀 快速开始

1.配置您的MCP客户端

将此添加到MCP配置中：

{
  "mcpServers": {
    "macos": {
      "command": "npx",
      "args": ["-y", "macos-app-mcp"],
      "env": {
        "MCP_NOTES_FOLDER": "ai",
        "MCP_REMINDERS_LIST": "ai",
        "MCP_ALLOW_DELETE": "false"
      }
    }
  }
}
客户端 配置位置
光标 Settings > Features > MCP
克劳德桌面版 ~/Library/Application Support/Claude/claude_desktop_config.json
帆板运动 Settings > Extensions > MCP
Gemini CLI ~/.gemini/config.json

2.开始使用

配置后，您可以询问您的AI助手：

  • What's on my calendar today?
  • Create a note titled 'Meeting Notes' with today's action items
  • Add a reminder to call John tomorrow at 10am
  • Find contact info for Alice

🛠️ 可用工具（共29个）

应用程序 工具名称 描述
备注 notes_query 从macOS notes应用程序搜索或列出笔记
notes_get 以纯文本形式阅读笔记内容（HTML剥离）
notes_create 创建一个带有标题和内容的新笔记
notes_update 更新现有笔记的内容
notes_delete 删除注释（需要标题确认）
notes_list_folders 列出所有可用的笔记文件夹
提醒事项 reminders_list 列出不完整的提醒（可按列表筛选）
reminders_add 向特定列表添加新提醒
reminders_complete 将提醒标记为已完成
reminders_update 更新提醒的文本或截止日期
reminders_delete 删除提醒（需要文本确认）
reminders_list_lists 列出所有可用的提醒列表
日历 calendar_list 列出特定日期的事件
calendar_create_event 创建新的日历事件
calendar_delete_event 删除事件（需要摘要确认）
calendar_list_calendars 列出所有可用日历
联系人 contacts_search 按姓名搜索联系信息（电话/电子邮件）
contacts_list 列出所有联系人（有限输出）
contacts_get_details 按确切姓名获取全面的联系信息
contacts_search_by_phone 按电话号码搜索联系人
contacts_search_by_email 通过电子邮件地址搜索联系人
消息 call_number 通过FaceTime或iPhone发起电话呼叫
message_send 向联系人或号码发送iMessage
恢复 recovery_list 列出可恢复（删除/修改）的项目
recovery_details 获取操作详细信息以进行恢复评估
recovery_recover 执行本机或基于日志的恢复
recovery_stats 查看恢复系统的运行状况和容量
日志 logs_recent 查看按时间顺序排列的最近活动日志
logs_by_app 按特定应用程序筛选操作日志

⚙️ 配置

变量 默认值 描述
MCP_ALLOW_DELETE false 启用/禁用删除功能
MCP_ALLOW_UPDATE false 启用/禁用编辑功能
MCP_NOTES_FOLDER ai 新笔记的默认文件夹；如果不存在，则自动创建
MCP_REMINDERS_LIST ai 新提醒的默认列表；如果不存在，则自动创建
MCP_LOGGING_ENABLED true 恢复功能所需

🔧 发展

设置

git clone https://github.com/zenheart/macos-app-mcp
cd macos-app-mcp
pnpm install
pnpm build

测试

# Run unit tests (mocked, safe to run)
pnpm test

# Run unit tests in watch mode
pnpm test:watch

# Run with coverage report
pnpm test:coverage

集成测试

⚠️ 警告：集成测试与 真正的macOS应用程序 （备注、提醒、日历）。测试项目前缀为 MCP-TEST- 用于识别。

# Run integration tests against real macOS apps
pnpm test:integration

已知限制：

  • 备注：由于iCloud同步延迟，新创建的笔记可能无法通过AppleScript立即找到
  • 联系人：联系人应用程序必须运行才能通过与联系人相关的测试
  • 由于这些macOS应用程序的限制，跳过了一些测试

MCP检查员游乐场

MCP检查器为手动测试工具提供了一个交互式web UI：

# Build and start MCP Inspector (opens http://localhost:5173)
pnpm playground:dev

# Or if already built
pnpm playground

检查员允许您：

  • 浏览所有可用工具
  • 使用自定义参数执行工具
  • 查看响应和调试问题
  • 监控服务器日志

开发流程

  1. 在中更改源文件 src/
  2. 跑 pnpm dev 用于监视模式（保存时自动重建）
  3. 使用单元测试进行测试： pnpm test
  4. 交互式测试： pnpm playground:dev
  5. 在提交PR之前运行集成测试： pnpm test:integration

类型检查

pnpm lint

发布工作流

该项目使用GitHub Actions的自动版本碰撞：

# Patch release (1.0.2 -> 1.0.3) - for bug fixes
pnpm release

# Minor release (1.0.2 -> 1.1.0) - for new features
pnpm release:minor

# Major release (1.0.2 -> 2.0.0) - for breaking changes
pnpm release:major

这将：

  1. 运行棉绒和测试
  2. 构建项目
  3. 将版本插入 package.json
  4. 创建一个git标签（例如。， v1.0.3)
  5. 推送到GitHub→ 触发自动NPM发布

📄 许可证

MIT© 曾哈特

相关 MCP