使用说明

提醒MCP服务器

[！注意] 这个项目是由一个大型语言模型（LLM）自主生成的，并有部分人工审查。

用于通过EventKit控制macOS提醒的模型上下文协议（MCP）服务器。此服务器使AI助手和自动化工具能够以编程方式创建、读取、更新和删除提醒和列表，而无需自动化提醒UI应用程序。

特性

✅ 完整的CRUD操作：创建、阅读、更新和删除提醒
📋 列表管理：创建、列出和删除提醒列表
🔍 智能搜索：通过过滤按名称搜索提醒
📅 弹性日期：支持定时和全天截止日期，以及通知提醒
🎯 优先级：从0到9设置优先级（低/中/高）
📊 分页：高效处理大型结果集
🎨 双格式：以人类可读的Markdown或机器可读的JSON格式输出
🔒 类型安全：使用TypeScript和Zod验证构建

目录策略和信任信息

该存储库包括明确的文档，以符合Anthropic软件目录政策：

隐私政策： PRIVACY.md
合规性映射： DIRECTORY_COMPLIANCE.md
支持渠道：GitHub问题+维护人员电子邮件（请参阅支持)

目录提示示例（核心用例）

使用以下提示验证核心功能：

“创建一个名为的提醒 Submit tax forms 在我的 Personal 名单明天下午5点到期。”
“显示中所有未完成的提醒 Work 以JSON格式列出。"
“标记提醒 Book dentist appointment 已在我的 Personal 列表。"

先决条件

macOS（用于提醒/事件工具包）
Node.js 18+和npm
Swift工具链可用(xcrun swiftc)用于构建辅助二进制文件

安装

# Clone or download this repository
cd reminders-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

用法

作为独立服务器

使用stdio传输运行（默认）：

npm start

使用HTTP传输运行：

TRANSPORT=http PORT=3000 npm start

与MCP检查员一起

以交互方式测试您的服务器：

npx @modelcontextprotocol/inspector node dist/index.js

构建Claude桌面 `.mcpb` 包裹

如果 @anthropic-ai/dxt 发出a .dxt 您可以在计算机上生成文件 .mcpb 使用以下方式上传工件：

npm run package:mcpb

此脚本：

构建TypeScript(npm run build)
运行Anthropic包装(npx @anthropic-ai/dxt pack)
复制已制作的 .dxt 等同于 .mcpb 项目根目录中的文件

然后上传生成的 .mcpb 提交表格中的文件。

与Claude Desktop集成

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "reminders": {
      "command": "node",
      "args": ["/path/to/reminders-mcp-server/dist/index.js"]
    }
  }
}

可用工具

提醒操作

`reminders_create`

创建一个新的提醒，包括可选的截止日期、备注和优先级。

参数：

name （字符串，必填）：提醒标题
listName （string，必填）：要添加的列表
body （字符串，可选）：注释/详细信息
dueDate （字符串，可选）：到期日期和时间（ISO 8601）
allDayDueDate （字符串，可选）：全天到期日
remindMeDate （字符串，可选）：通知时间
priority （数字，可选）：0-9（0=无，1-4=低，5-8=中，9=高）
responseFormat （字符串，可选）：“markdown”或“json”

例子：

{
  "name": "Submit quarterly report",
  "listName": "Work",
  "body": "Include sales figures and projections",
  "dueDate": "2024-03-31T17:00:00",
  "priority": 9
}

`reminders_list`

列出带有过滤和分页功能的提醒。

参数：

listName （字符串，可选）：按列表筛选
completed （布尔值，可选）：按完成状态筛选
limit （数字，可选）：最大结果（默认值：50，最大值：200）
offset （数字，可选）：分页偏移
responseFormat （字符串，可选）：“markdown”或“json”

例子：

{
  "listName": "Work",
  "completed": false,
  "limit": 20
}

`reminders_search`

按名称搜索提醒。

参数：

query （string，必填）：搜索字符串
listName （字符串，可选）：限制到特定列表
completed （布尔值，可选）：按状态筛选
limit （数字，可选）：最大结果
offset （数字，可选）：分页偏移
responseFormat （字符串，可选）：“markdown”或“json”

例子：

{
  "query": "meeting",
  "listName": "Work",
  "completed": false
}

`reminders_update`

更新现有提醒。

参数：

listName （字符串，必填）：包含提醒的列表
reminderName （字符串，必填）：当前提醒名称
newName （字符串，可选）：新名称
body （字符串，可选）：新注释
dueDate （字符串，可选）：新的截止日期
allDayDueDate （字符串，可选）：新的全天日期
remindMeDate （字符串，可选）：新通知时间
priority （数字，可选）：新优先级
completed （布尔值，可选）：标记完整/不完整
responseFormat （字符串，可选）：“markdown”或“json”

例子：

{
  "listName": "Work",
  "reminderName": "Old task name",
  "newName": "Updated task name",
  "completed": true
}

`reminders_delete`

永久删除提醒。

参数：

listName （字符串，必填）：包含提醒的列表
reminderName （字符串，必填）：提醒删除

例子：

{
  "listName": "Personal",
  "reminderName": "Completed task"
}

清单的操作

`reminders_list_lists`

获取所有提醒列表。

参数：

responseFormat （字符串，可选）：“markdown”或“json”

例子：

{
  "responseFormat": "json"
}

`reminders_create_list`

创建新的提醒列表。

参数：

name （字符串，必填）：列表名称（最多200个字符）

例子：

{
  "name": "Project Alpha"
}

`reminders_delete_list`

删除列表及其所有提醒。

参数：

name （字符串，必填）：列表名称

例子：

{
  "name": "Old Project"
}

日期格式

日期应采用ISO 8601格式提供：

随着时间的推移: "2024-12-31T15:30:00" （2024年12月31日下午3:30）
全天的: "2024-12-31" （无具体时间）
带时区: "2024-12-31T15:30:00-08:00" （PST）

优先级

0：无优先级
1-4：低优先级
5-8：中等优先级
9：高优先级

响应格式

Markdown（默认）

具有视觉结构的人类可读格式：

## Reminders (3)

### Work (2)

**Submit report**
  Complete quarterly analysis
  _Due: 3/31/2024, 5:00 PM • Priority: High (9) • List: Work_

**Team meeting**
  _Due: 3/15/2024, 2:00 PM • Priority: Medium (5) • List: Work_

对象符号

用于编程的结构化数据：

{
  "total": 3,
  "count": 3,
  "offset": 0,
  "reminders": [
    {
      "id": "x-apple-reminder://...",
      "name": "Submit report",
      "body": "Complete quarterly analysis",
      "completed": false,
      "dueDate": "2024-03-31T17:00:00.000Z",
      "priority": 9,
      "listName": "Work"
    }
  ],
  "hasMore": false
}

错误处理

所有工具都包括全面的错误处理：

无效日期：“无效日期：…”
缺少列表：“未找到列表'xyz'”
缺少提醒：“在指定列表中找不到提醒”
权限问题：“提醒访问被拒绝…”

错误包括解决问题的有用提示。

发展

项目结构

reminders-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── constants.ts          # Shared constants
│   ├── schemas/
│   │   └── index.ts          # Zod validation schemas
│   ├── services/
│   │   ├── eventkit.ts       # EventKit helper adapter
│   │   └── formatting.ts     # Output formatting
│   └── tools/
│       ├── reminders.ts      # Reminder tools
│       └── lists.ts          # List tools
├── native/
│   └── RemindersEventKitHelper.swift  # Native helper implementation
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

构建命令

# Build TypeScript
npm run build

# Watch mode (auto-rebuild)
npm run dev

# Start server
npm start

测试

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

局限性

仅限macOS：需要macOS和提醒应用程序
需要日历权限：正在运行的进程必须具有完整的提醒/日历访问权限
无UI自动化：直接使用EventKit（不依赖AppleScript应用程序自动化）
仅限本地：必须与提醒应用程序在同一台计算机上运行
列表标识：按列表中的名称（而不是按ID）标识提醒
标签/子任务：此服务器尚未公开

故障排除

权限错误

授予提醒访问权限：

打开系统设置→ 隐私和安全→ 日历
启用终端/节点/MCP客户端进程的访问
更改权限后重新启动MCP进程

“未找到列表”

验证列表名称是否准确（区分大小写）
使用 reminders_list_lists 查看可用列表

日期解析错误

确保日期采用ISO 8601格式
例子： "2024-12-31T15:00:00" 不 "12/31/2024 3pm"

EventKit错误

确保该流程具有完整的日历权限
权限更改后重新启动MCP主机应用程序
跑 npm run build 并重新启动服务器以刷新辅助二进制文件

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

TypeScript编译时没有错误(npm run build)
所有模式都使用 .strict() 验证
工具描述包括综合示例
错误消息具有可操作性和帮助性

支持

对于问题、疑问或建议：

GitHub问题：https://github.com/thegeneralist01/reminders-mcp-server/issues
电子邮件：thegeneralist01@gmail.com

使用说明

提醒MCP服务器

特性

目录策略和信任信息

目录提示示例（核心用例）

先决条件

安装

用法

作为独立服务器

与MCP检查员一起

构建Claude桌面 .mcpb 包裹

与Claude Desktop集成

可用工具

提醒操作

reminders_create

reminders_list

reminders_search

reminders_update

reminders_delete

清单的操作

reminders_list_lists

reminders_create_list

reminders_delete_list

日期格式

优先级

响应格式

Markdown（默认）

对象符号

错误处理

发展

项目结构

构建命令

测试

局限性

故障排除

权限错误

“未找到列表”

日期解析错误

EventKit错误

许可证

贡献

支持

相关 MCP

macOS 屏幕捕获与 UI 自动化工具

AI代理操作系统

苹果提醒事项与日历 MCP 服务器

苹果提醒事项与日历 MCP 服务器

OmniFocus 命令行工具

macOS自动化服务

构建Claude桌面 `.mcpb` 包裹

`reminders_create`

`reminders_list`

`reminders_search`

`reminders_update`

`reminders_delete`

`reminders_list_lists`

`reminders_create_list`

`reminders_delete_list`