让你的 AI 通过 `mcp-caldav` 获得真正的日历超能力
I’m ready to translate the article, but I need the full text you’d like translated. Could you please provide the content (excluding the source line and any code blocks) that you want converted to Simplified Chinese? Once I have that, I’ll keep the source link and formatting exactly as you requested.
TL;DR
“我可以让我的 AI 实际查看并管理我的日历吗？”
mcp‑caldav 是一个 MCP 服务器，可将任何兼容 CalDAV 的日历（Nextcloud、iCloud、FastMail、Yandex 等）桥接到你的 AI 工具。这样 AI 就可以：
- 列出日历
- 读取日程
- 创建事件（提醒、参与者、重复）
- 按 UID 搜索或删除事件
该项目已被收录在流行的 awesome‑mcp‑servers 集合中，证明它不仅仅是个玩具。
项目功能
| Direction | Role |
|---|---|
| CalDAV | 使用日历语言——事件、UID、RRULE、参与者、提醒、类别、优先级。 |
| MCP | 提供一套干净的工具供 LLM 调用——列出日历、创建事件、获取事件、搜索、删除。 |
示例工作流
- “本周我的日历上有什么？”
- “在明天下午创建一个 30 分钟的会议，参加者是 Alex。”
- “显示下个月所有标记为 #deep‑work 的事件。”
- “删除我们刚创建的 Test meeting。”
没有任何魔法——只是你的日历和 AI 之间坚实的管道。
Repository Layout
caldav-mcp/
├─ src/
│ └─ mcp_caldav/
│ ├─ __init__.py # main entry point / CLI
│ ├─ server.py # MCP server (tools, protocol wiring)
│ └─ client.py # CalDAV client wrapper (auth, HTTP, (de)serialization)
├─ tests/
│ ├─ test_server.py
│ └─ test_client.py
├─ e2e/ # end‑to‑end tests against a real CalDAV server
├─ pyproject.toml # packaging & dependency config
├─ Makefile # dev commands (make test, make check, …)
├─ README.md
├─ USAGE.md
└─ QUICKSTART.md一个干净、适合中级开发者的友好布局：明确的入口点、关注点分离，以及真实的测试套件。
核心设计要点
- 严格类型 –
mypy严格规则 - 快速 linting/格式化 –
ruff - 预提交钩子 – 保持风格和检查的一致性
运行 mcp‑caldav
使用 uv（推荐）
git clone https://github.com/madbonez/caldav-mcp.git
cd caldav-mcp
# 安装运行时 + 开发依赖，创建 .venv，生成 uv.lock
uv sync --dev运行服务器：
uv run mcp-caldav # 来自本地检出或直接运行已发布的包而无需检出：
uvx mcp-caldav使用 pip
pip install -e .
mcp-caldav所有方式都会暴露一个普通的 Python CLI 入口点。
Source: …
配置
服务器从环境变量读取设置：
export CALDAV_URL="https://caldav.example.com/"
export CALDAV_USERNAME="your-username"
export CALDAV_PASSWORD="your-password"常用 CalDAV 接口
| 提供商 | URL |
|---|---|
| Yandex Calendar | https://caldav.yandex.ru/ |
| Google Calendar (CalDAV + OAuth) | https://apidata.googleusercontent.com/caldav/v2/ |
| Nextcloud | https://your-domain.com/remote.php/dav/calendars/username/ |
| ownCloud | https://your-domain.com/remote.php/dav/calendars/username/ |
| Apple iCloud | https://caldav.icloud.com/（通常使用应用专用密码） |
| FastMail | https://caldav.fastmail.com/dav/calendars/user/ |
注意： Yandex 实施了严格的速率限制（≈ 60 秒/兆字节）。大量写入操作可能会触发 504 超时。若需更高吞吐量，建议使用 Nextcloud 或 Google。详细信息请参见
PROVIDER_NOTES.md。
与 Cursor（或任何 MCP‑aware 客户端）集成
添加 mcp‑caldav 作为全局 MCP 服务器，以便 AI 能自动调用日历工具。
使用 uvx（无需本地检出）
{
"mcpServers": {
"mcp-caldav": {
"command": "uvx",
"args": ["mcp-caldav"],
"env": {
"CALDAV_URL": "https://caldav.example.com/",
"CALDAV_USERNAME": "your-username",
"CALDAV_PASSWORD": "your-password"
}
}
}
}使用本地检出
{
"mcpServers": {
"mcp-caldav": {
"command": "uv",
"args": [
"run",
"--directory",
"/Users/you/dev/caldav-mcp",
"mcp-caldav"
],
"env": {
"CALDAV_URL": "https://caldav.example.com/",
"CALDAV_USERNAME": "your-username",
"CALDAV_PASSWORD": "your-password"
}
}
}
}配置完成后，Cursor（或任何支持 MCP 的客户端）将向 LLM 提供以下工具。
暴露的 MCP 工具
| 工具 | 描述 |
|---|---|
| caldav_list_calendars | 返回您可以访问的所有日历（个人、工作、共享，…）。对 AI 选择目标日历或发现可用日历很有帮助。 |
| caldav_create_event | 创建一个新事件，包含： • 标题、描述、地点 • 开始/结束时间戳或持续时间 • 重复规则（每日/每周/每月/每年） • 类别/标签 • 优先级（0‑9） • 参与者及其状态 • 多个提醒 |
| caldav_get_events | 获取指定日期范围内的事件。返回 UID、类别、优先级、参与者及其状态、重复细节、提醒等。 |
| caldav_get_today_events | 返回今天的所有事件，包括全天条目。非常适合“我星期四有什么安排？”之类的查询。 |
| caldav_search_events | 按关键字、标签或其他元数据搜索。 |
| caldav_delete_event | 根据 UID 删除事件。 |
这些工具为您在 LLM 驱动的工作流中提供了对任何 CalDAV 日历的完整 CRUD 接口。
快速回顾
- 克隆 / 安装 仓库（uv 或 pip）。
- 为你的 CalDAV 服务器设置环境变量。
- 运行
mcp-caldav。 - 配置 你的 MCP 客户端（Cursor 等）指向该服务器。
- 向你的 AI 提出自然语言的日历问题——它将在后台调用相应的 MCP 工具。
享受真正驻留在 AI 大脑中的日历！
CalDAV MCP 工具概览
caldav_get_week_events
返回本周的事件。
- 可选定义一周的起始是 “今天” 还是 星期一。
- 非常适合每周计划提示。
高级操作
caldav_get_event_by_uid
通过 UID 查找单个事件。
使用场景： “展示一下你刚才提到的那次会议的更多细节。”
caldav_delete_event
通过 UID 删除事件。
使用场景： 编程方式清理测试事件或取消会议。
caldav_search_events
搜索条件：
- text（标题 / 描述）
- location（地点）
- attendees（参与者）
示例：
- “查找今年标题中包含 ‘performance review’ 的所有事件。”
- “显示上个月与 Alice 的会议。”
- “列出下季度标记为 #deep‑work 的所有事件。”
开发工具
项目配备了坚实的质量保证栈：
| 工具 | 目的 |
|---|---|
| ruff | 快速 linting + 格式化 |
| mypy | 静态类型检查 |
| pre‑commit | 在提交前运行检查 |
入门
# Install all dependencies (including dev group)
uv sync --group dev常用 Make 命令
| 命令 | 描述 |
|---|---|
make check | 运行 全部 质量检查 |
make lint | 仅 lint |
make format | 格式化代码 |
make type-check | 运行静态类型检查 |
make test | 运行 全部 测试 |
make test-unit | 仅运行 单元 测试 |
make test-e2e | 运行 端到端 测试（需要真实的 CalDAV 服务器） |
make test-cov | 在终端显示覆盖率 |
make coverage-html | 生成 HTML 覆盖报告（htmlcov/） |
端到端测试设置
-
复制示例 env 文件:
cp .env.e2e.example .env.e2e -
在
.env.e2e中填写真实的 CalDAV 凭证。 -
运行测试:
make test-e2e
awesome-mcp-servers 列表
awesome-mcp-servers 列表精选高质量的 MCP 服务器。mcp-caldav 非常契合，因为：
- 通过 标准协议 将 AI 连接到真实世界数据（你的日历）。
- 代码库干净、体积适中，易于浏览。
- 测试覆盖良好（单元测试 + E2E）。
- 文档齐全（
README.md、USAGE.md、QUICKSTART.md、PROVIDER_NOTES.md）。
为什么把这个仓库当作参考？
- 关注点分离： 传输层（MCP） 与 领域逻辑（CalDAV 客户端） 分开。
- 表达力强的工具表面： 小巧却功能强大的 API。
- 即插即用： 可直接使用现有的 CalDAV 服务器，无需重新造轮子。
如果你希望你的 AI 不仅仅是聊天——例如真正管理你的日程——mcp-caldav 是一个坚实的起点：
- 使用 标准协议（CalDAV）。
- 暴露明确的 MCP 工具。
- 经受足够的实战考验，入选 awesome-mcp-servers。
🔗 https://github.com/madbonez/caldav-mcp
欢迎将其接入你的系统或进行扩展（例如添加更新/补丁操作或更丰富的搜索功能）。这正是构建严肃 MCP 工作流的人所需要的工作方式。