AI导哈

CalDAV协议服务器

MCP CalDAV服务器是一个通用的CalDAV协议集成服务器，支持与多种CalDAV兼容的日历服务（如Google日历、Nextcloud、iCloud等）进行交互，提供日历事件管理功能。

  • by madbonez
  • Python
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 madbonez/caldav-mcp

使用说明

MCP CalDAV服务器

用于CalDAV协议集成的通用MCP服务器。适用于任何与CalDAV兼容的日历服务器，包括Yandex日历、谷歌日历（通过CalDAV）、Nextcloud、ownCloud、苹果iCloud等。

📖 快速开始：参见 QUICKSTART.md 获取快速入门指南 uv. 🔧 光标设置：参见 CURSOR_SETUP.md 有关Cursor IDE配置的详细说明。

特性

  • 列出可用日历
  • 创建带有提醒和与会者的日历事件
  • 获取今天、本周或自定义日期范围的事件
  • 适用于任何兼容CalDAV的服务器（Yandex、谷歌、Nextcloud、ownCloud、iCloud等）

安装

使用紫外线（推荐）

首先，如果你还没有安装uv：

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

窗户：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后安装项目：

uv sync --dev

这将：

  • 创建虚拟环境(.venv)
  • 安装所有依赖项，包括开发依赖项
  • 生成一个 uv.lock 文件

使用uvx（无需安装即可运行）

您也可以直接运行服务器，而无需安装：

uvx mcp-caldav

使用pip

pip install -e .

配置

设置以下环境变量：

export CALDAV_URL="https://caldav.example.com/"
export CALDAV_USERNAME="your-username"
export CALDAV_PASSWORD="your-password"

CalDAV服务器URL

常见的CalDAV服务器URL：

  • Yandex日历: https://caldav.yandex.ru/
  • 谷歌日历: https://apidata.googleusercontent.com/caldav/v2/ （需要OAuth设置）
  • 云端下一站: https://your-domain.com/remote.php/dav/calendars/username/
  • ownCloud: https://your-domain.com/remote.php/dav/calendars/username/
  • 苹果iCloud: https://caldav.icloud.com/ （需要特定于应用程序的密码）
  • 快速邮件: https://caldav.fastmail.com/dav/calendars/user/

备注：一些服务器需要特定于应用程序的密码，而不是常规密码。查看日历提供商的文档，了解CalDAV设置说明。

用法

IDE集成（游标）

要在Cursor中使用此MCP服务器：

  1. 打开光标设置→ 特性→ MCP服务器→ + 添加新的全局MCP服务器
  2. 添加以下配置：

使用uvx（推荐-无需安装）：

{
  "mcpServers": {
    "mcp-caldav": {
      "command": "uvx",
      "args": ["mcp-caldav"],
      "env": {
        "CALDAV_URL": "https://caldav.example.com/",
        "CALDAV_USERNAME": "your-username",
        "CALDAV_PASSWORD": "your-password"
      }
    }
  }
}

使用本地安装（之后 uv sync 或 pip install):

{
  "mcpServers": {
    "mcp-caldav": {
      "command": "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", "/path/to/caldav", "mcp-caldav"],
      "env": {
        "CALDAV_URL": "https://caldav.example.com/",
        "CALDAV_USERNAME": "your-username",
        "CALDAV_PASSWORD": "your-password"
      }
    }
  }
}

Yandex日历示例：

{
  "mcpServers": {
    "mcp-caldav": {
      "command": "uvx",
      "args": ["mcp-caldav"],
      "env": {
        "CALDAV_URL": "https://caldav.yandex.ru/",
        "CALDAV_USERNAME": "your-username@yandex.ru",
        "CALDAV_PASSWORD": "your-app-password"
      }
    }
  }
}

⚠️ 备注Yandex日历具有严格的速率限制（自2021年以来每MB 60秒）。 写操作（创建/更新/删除）可能会遇到504超时，因此会间隔出请求并引入手动延迟。 对于编写繁重的工作负载，可以考虑使用谷歌日历或Nextcloud。 看 提供者NOTES.md 了解详情。

测试状态：端到端测试目前仅针对Yandex日历运行。其他CalDAV提供商遵循相同的协议，应该可以工作，但它们还没有经过集成测试。

Nextcloud示例：

{
  "mcpServers": {
    "mcp-caldav": {
      "command": "uvx",
      "args": ["mcp-caldav"],
      "env": {
        "CALDAV_URL": "https://your-domain.com/remote.php/dav/calendars/username/",
        "CALDAV_USERNAME": "your-username",
        "CALDAV_PASSWORD": "your-password"
      }
    }
  }
}

作为MCP服务器

服务器可以与MCP兼容的客户端一起使用：

使用紫外线（之后 uv sync):

uv run mcp-caldav

注： uvx 仅适用于PyPI发布的包。对于当地发展，使用 uv run mcp-caldav 之后 uv sync.

使用pip（安装后）：

mcp-caldav

或者使用自定义选项：

uv run mcp-caldav --caldav-url "https://caldav.example.com/" \
                   --caldav-username "your-username" \
                   --caldav-password "your-password" \
                   --verbose

可用工具

基本操作：

  • caldav_list_calendars -列出所有可用日历
  • caldav_create_event -创建新的日历事件（支持重复、类别、优先级、与会者）
  • caldav_get_events -获取日期范围内的事件（返回扩展字段：UID、类别、优先级、与会者、重复）
  • caldav_get_today_events -获取今天的活动
  • caldav_get_week_events -获取本周活动

高级操作：

  • caldav_get_event_by_uid -通过UID获取特定事件
  • caldav_delete_event -按UID删除事件
  • caldav_search_events -按文本、与会者或位置搜索事件

支持的功能：

  • 重复事件（RRULE）-每日、每周、每月、每年模式
  • 分类/标签-按类别组织活动
  • 优先级-设置优先级（0-9，0=最高）
  • 具有状态的与会者-跟踪接受状态（接受/拒绝/暂定/需要采取行动）
  • 提醒-每个事件有多个提醒

发展

代码质量

该项目使用多种工具来确保代码质量：

  • 米皮 -具有严格规则的静态类型检查
  • 颈毛 -快速换行和代码格式化
  • 预承诺 -提交前自动检查

运行质量检查：

# Install dev dependencies
uv sync --group dev

# Run all checks
make check

# Or individually
make lint
make format
make type-check

# Or using pre-commit
make pre-commit-run

设置预提交挂钩：

uv run pre-commit install

看 代码_质量.md 了解详细信息。

运行测试

单元测试（带模拟）：

make test
# or
make test-unit

E2E测试（需要真实的CalDAV服务器）：

# Create .env.e2e file with your credentials, then:
make test-e2e

所有测试：

make test

覆盖范围：

make test-cov        # Terminal report
make coverage-html   # HTML report

看 tests/e2e/README.md 有关e2e测试的更多详细信息。

项目结构

caldav/
├── src/
│   └── mcp_caldav/
│       ├── __init__.py      # Main entry point
│       ├── server.py        # MCP server implementation
│       └── client.py         # CalDAV client wrapper
├── tests/
│   ├── test_server.py       # Server unit tests
│   ├── test_client.py       # Client unit tests
│   └── e2e/                 # End-to-end tests with real server
│       ├── test_client_e2e.py
│       └── conftest.py
├── pyproject.toml           # Project configuration
├── Makefile                 # Development commands
└── README.md                # This file

许可证

有关详细信息，请参阅LICENSE文件。

相关 MCP