# apple-reminders-mcp-server

一个基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 的 macOS 提醒事项工具服务。
通过 AppleScript 操作系统原生「提醒事项」，以标准 MCP 协议（stdio 传输）暴露增删改查工具，
可被任何 MCP 兼容的 Agent / Host 接入使用。

> 本项目从 [calendar-agent](https://github.com/yzheeng/calendar-agent) 的内置工具层重构而来——
> 将进程内硬编码的工具函数解耦为独立、可复用的 MCP Server。

## 提供的工具

| 工具 | 说明 |
| --- | --- |
| `create_reminder` | 创建提醒事项，支持指定截止时间 |
| `list_reminders` | 列出未完成提醒，支持按时间范围过滤 |
| `list_completed_reminders` | 列出已完成提醒，按完成时间范围过滤 |
| `update_reminder` | 修改指定提醒的标题或时间 |
| `complete_reminder` | 标记指定提醒为已完成 |
| `delete_reminder` | 删除指定提醒 |

## 环境要求

- macOS（依赖系统「提醒事项」与 AppleScript）
- Python 3.12+
- [uv](https://github.com/astral-sh/uv)

## 快速开始

```bash
git clone https://github.com/yzheeng/apple-reminders-mcp-server
cd apple-reminders-mcp-server
uv sync
uv run apple-reminders-mcp-server
```

首次调用工具时，macOS 会弹窗请求「自动化」权限（控制提醒事项），允许即可。

## 在 MCP Host 中接入

在你的 Host 配置中按如下方式声明（以通用 JSON 配置为例）：

```json
{
  "mcpServers": {
    "reminders": {
      "command": "uv",
      "args": ["--directory", "/path/to/reminder-mcp-server", "run", "reminder-mcp-server"]
    }
  }
}
```

## 协议说明

- 传输方式：stdio（JSON-RPC 2.0，行分帧）