使用说明

用于macOS提醒的MCP服务器

用于通过EventKit管理macOS提醒的MCP服务器。

此FastMCP服务器通过模型上下文协议（MCP）提供对macOS提醒应用程序的本地访问，使AI助手能够创建、读取、更新和删除提醒和列表。

需求

macOS 14.0+（索诺玛或更高版本）
Python 3.10+

安装

# Clone the repository
git clone <your-repo-url>
cd jons-mcp-reminders

# Install with uv
uv pip install -e .

权限

首次运行时，服务器将请求访问提醒。您必须在以下位置授予此权限：

系统设置>隐私和安全>提醒

终端应用程序（或您的Python环境）必须具有访问提醒的权限。

运行服务器

uv run jons-mcp-reminders

添加到克劳德代码

# Register the MCP server with Claude Code
claude mcp add jons-mcp-reminders -- uv run --project /path/to/jons-mcp-reminders jons-mcp-reminders

添加到Claude桌面

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

{
  "mcpServers": {
    "jons-mcp-reminders": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/jons-mcp-reminders",
        "jons-mcp-reminders"
      ]
    }
  }
}

替换 /path/to/jons-mcp-reminders 以及此存储库的实际路径。

可用工具

列表管理（5个工具）

工具	说明
`list_reminder_lists`	获取所有提醒列表
`get_reminder_list`	按ID获取特定列表
`create_reminder_list`	使用可选的十六进制颜色创建新列表
`update_reminder_list`	更新列表标题/颜色
`delete_reminder_list`	删除列表（及其所有提醒）

提醒CRUD（7个工具）

工具	说明
`get_reminders`	使用过滤器获取提醒（列表、完成、截止日期）
`get_reminder`	按ID获取单个提醒
`create_reminder`	创建标题、注释、URL、截止日期、优先级、位置
`update_reminder`	更新所有提醒字段，包括位置
`complete_reminder`	切换完成状态
`delete_reminder`	删除提醒
`move_reminder`	将提醒移动到其他列表

批量操作（3个工具）

工具	说明
`complete_reminders`	批量完成多个提醒
`delete_reminders`	批量删除多个提醒
`add_reminders`	按标题快速添加多个提醒

搜索（1个工具）

工具	说明
`search_reminders`	按标题/注释搜索提醒（不区分大小写）

优先级值

优先级	价值	提醒应用程序
无	0	无标志
高	1	！！！
中等	5	！！
低	9	！

基于位置的提醒

您可以创建根据到达或离开位置触发的提醒。这 create_reminder 和 update_reminder 工具接受a location 参数包含以下字段：

字段	类型	描述
`title`	string	位置的显示名称（例如，“家”、“办公室”）
`latitude`	float	纬度坐标（-90到90）
`longitude`	float	经度坐标（-180到180）
`radius`	float	土工围栏半径（单位：米）（默认值：100，最大值：10000）
`proximity`	string	何时触发： `"enter"` （到达）或 `"leave"` （出发）

示例：使用位置创建提醒

await create_reminder(
    title="Buy groceries",
    location={
        "title": "Whole Foods",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "radius": 100.0,
        "proximity": "enter"
    }
)

示例：从提醒中删除位置

await update_reminder(reminder_id, clear_location=True)

注：基于位置的提醒需要在设备上启用位置服务才能激活触发器。

已知限制

不支持的部分：EventKit不公开提醒列表中的部分/标题（例如，杂货列表中的“冻结”、“生产”）。这是一个没有公共API的UI-only功能。
颜色偏移：同步时，由于iCloud颜色空间转换，颜色可能会略有偏移（每个RGB通道约30个单位）。这是预期的行为。
Exchange日历：Exchange帐户上的提醒ID在初始同步后可能会更改。iCloud日历具有稳定的ID。

发展

设置

# Install with dev dependencies
uv pip install -e ".[dev]"

运行测试

# Run all tests
uv run pytest

# Run integration tests (requires Reminders access)
uv run pytest tests/test_integration.py -v

# Run with coverage
uv run pytest --cov=src

代码质量

# Type check
uv run mypy src/jons_mcp_reminders

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests

项目结构

jons-mcp-reminders/
├── src/
│   └── jons_mcp_reminders/
│       ├── __init__.py          # Package exports
│       ├── constants.py         # Configuration constants
│       ├── exceptions.py        # Custom exceptions
│       ├── models.py            # Pydantic models
│       ├── converters.py        # EventKit <-> Python conversions
│       ├── store.py             # ReminderStore singleton
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           ├── __init__.py      # Tool exports
│           ├── lists.py         # List management tools
│           ├── reminders.py     # Reminder CRUD tools
│           ├── batch.py         # Batch operation tools
│           └── search.py        # Search tool
├── tests/
│   ├── conftest.py              # Test fixtures
│   └── test_integration.py      # Integration tests
├── pyproject.toml               # Project configuration
├── CLAUDE.md                    # AI assistant guidance
└── README.md                    # This file

许可证

麻省理工学院