Radicale CalDAV MCP Server

一个基于 FastMCP / 官方 MCP Python SDK 构建的 Model Context Protocol (MCP) 服务器，它将 LLM 代理（如 Nous Hermes、Claude、OpenAI）连接到自托管的 Radicale CalDAV 日历和任务管理器。

功能特性

📅 日历事件（VEVENT）

• get_events：查询日期/时间范围内的事件，并可选择按 summary、description 和 location 进行关键词搜索。

• get_free_busy_slots：在任意 IANA 时区下，计算可配置工作时间内（例如 9:00 AM - 5:00 PM）开放且未占用的时间段。

• create_event：安排新事件，自动进行 ISO 校验、参会者邀请以及重叠/冲突检测。

• update_event：按 UID 修改现有事件，且不覆盖未变更的字段。

• delete_event：按 UID 删除事件。

📝 任务与待办事项（VTODO）

• list_todos：按状态（NEEDS-ACTION、COMPLETED、IN-PROCESS、CANCELLED、ALL）获取待处理或已完成的任务。

• create_todo：创建带有截止日期、优先级（1-9）和描述的任务。

• complete_todo：将任务标记为已完成，并自动添加完成时间戳。

🚀 传输方式与部署

• STDIO 传输：本地执行的默认传输方式（例如 Claude Desktop、本地代理）。

• SSE (Server-Sent Events) 传输：通过 HTTP 进行远程、常驻部署（例如 Coolify、Docker）。

Related MCP server: caldav-mcp

配置

通过环境变量或 .env 文件配置服务器：

本地快速开始

1. 安装

# Clone and enter directory
cd radicale-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. 配置环境

将 .env.example 复制为 .env 并设置你的凭据:

cp .env.example .env

3. 本地运行

STDIO 模式（本地管道）

python server.py --stdio

SSE 模式（HTTP 服务器）

python server.py --sse --host 0.0.0.0 --port 8000

4. 运行测试客户端

# Test via STDIO
python test_client.py --mode stdio

# Test via SSE (when server is running)
python test_client.py --mode sse --sse-url http://localhost:8000/sse

5. 运行自动化测试

pytest -v

Coolify 部署

在 Coolify 上零配置部署 MCP 服务器：

1. 在 Coolify 中创建新服务：Docker Compose 或 Dockerfile。

2. 将其指向此仓库，或直接粘贴 docker-compose.yml。

3. 在 Coolify UI 中设置以下环境变量：

   • RADICALE_BASE_URL=https://radicale.dubblu.app

   • RADICALE_USERNAME=mvela581

   • RADICALE_PASSWORD=your_password

   • RADICALE_CALENDAR_SLUG=seuspeptides

   • DEFAULT_TIMEZONE=America/New_York

   • MCP_TRANSPORT=sse

   • MCP_PORT=8000

4. 通过 Coolify 反向代理并使用你的域名（例如 https://mcp-calendar.yourdomain.com）暴露端口 8000。

5. 你的 SSE 端点将可通过以下地址访问:

   https://mcp-calendar.yourdomain.com/sse

LLM 代理集成（Nous Hill / Claude Desktop）

Claude Desktop 配置

将以下内容添加到你的 claude_desktop_config.json 中：

本地 STDIO：

{
  "mcpServers": {
    "radicale_calendar": {
      "command": "/path/to/radicale-mcp-server/.venv/bin/python",
      "args": ["/path/to/radicale-mcp-server/server.py", "--stdio"],
      "env": {
        "RADICALE_BASE_URL": "https://radicale.dubblu.app",
        "RADICALE_USERNAME": "mvela581",
        "RADICALE_PASSWORD": "your_password",
        "RADICALE_CALENDAR_SLUG": "seuspeptides",
        "DEFAULT_TIMEZONE": "America/New_York"
      }
    }
  }
}

远程 SSE（Coolify）：

{
  "mcpServers": {
    "radicale_calendar": {
      "url": "https://mcp-calendar.yourdomain.com/sse"
    }
  }
}

Nous Hermes 代理集成

工具定义根据类型规范从 docstring 自动生成。示例提示词用法：

{
  "name": "get_free_busy_slots",
  "arguments": {
    "start_date": "2026-08-26",
    "end_date": "2026-08-28",
    "slot_duration_minutes": 30,
    "working_hours_start": 9,
    "working_hours_end": 17,
    "timezone": "America/New_York"
  }
}

许可证

MIT