Calendar Consolidator MCP

日历合并器MCP

一个轻量级的系统，通过单向镜像和增量同步将多个日历（Microsoft 365、iCloud/CalDAV）整合到一个统一的日历中。

网站

• 英语
• 波斯语

特性

• 多源支持：微软Graph、CalDAV（即将推出）
• 单向同步：来源→ 目标日历镜像
• 增量更新：增量同步与变化检测
• MCP集成：通过MCP协议进行AI/代理控制
• Web用户界面：基于浏览器的简单配置
• 本地优先：SQLite数据库，无云依赖

快速开始

先决条件

• Python 3.10+
• Node.js 18+
• Git

安装

1. 克隆仓库:

git clone 
cd calendar-consolidator-mcp

1. 安装Python依赖项:

pip install -r requirements.txt
# Or with virtual environment:
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

1. 安装节点依赖项:

npm install

1. 初始化数据库:

python python/init_db.py

Windows安装程序（PowerShell）

在Windows上工作时使用附带的PowerShell帮助程序：

快速设置 （安装依赖关系，初始化数据库，并可选择创建虚拟环境）：

.\setup_windows.ps1

快速开始 （激活虚拟环境（如果可用）并启动web UI）：

.\run_windows.ps1

如果Windows阻止脚本执行，您可以运行：

Unblock-File .\setup_windows.ps1
Unblock-File .\run_windows.ps1

或者绕过单次运行的策略：

powershell -ExecutionPolicy Bypass -File .\setup_windows.ps1
powershell -ExecutionPolicy Bypass -File .\run_windows.ps1

手动设置 （如果你喜欢循序渐进）：

# Install Python dependencies
pip install -r requirements.txt

# Install Node dependencies
npm install

# Initialize database
python python/init_db.py

运行应用程序

启动web UI （推荐）：

npm start

然后打开http://localhost:3000在您的浏览器中。

Windows web用户界面:

# Using PowerShell script (recommended)
.\run_windows.ps1

# Or manually
npm start

以MCP服务器身份启动 （用于AI/代理集成）：

MCP_MODE=true node node/server/index.js

Windows MCP服务器:

# Using PowerShell script (with virtual environment)
$env:MCP_MODE = "true"
.\run_windows.ps1

# Or manually
$env:MCP_MODE="true"
node node/server/index.js

MCP工具可用

MCP服务器公开了以下用于AI/代理控制的工具：

配置工具：

• listCalendars -列出来自Microsoft Graph、Google、iCloud或CalDAV的可用日历
• getConfig -获取当前源、目标和设置配置

同步操作工具：

• previewSync -预览同步更改而不进行更改（模拟运行）
• syncOnce -对源或所有源执行日历同步
• getSyncStatus -获取当前同步状态和最近的日志

有关详细的工具模式和示例，请参阅 0-docs/04-api-design/01-mcp-tools.md

MCP配置设置

要将此MCP服务器与Claude Desktop或Cursor一起使用，请在MCP配置中添加以下内容：

适用于克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "calendar-consolidator": {
      "command": "node",
      "args": [
        "/absolute/path/to/calendar-consolidator-mcp/node/server/index.js"
      ],
      "env": {
        "MCP_MODE": "true"
      }
    }
  }
}

对于光标 (.cursor/mcp.json 在您的工作空间中）：

{
  "mcpServers": {
    "calendar-consolidator": {
      "command": "node",
      "args": [
        "node/server/index.js"
      ],
      "env": {
        "MCP_MODE": "true"
      }
    }
  }
}

替换 /absolute/path/to/calendar-consolidator-mcp 安装的实际路径。

项目结构

calendar-consolidator-mcp/
├── python/               # Python sync engine
│   ├── connectors/      # API connectors (Graph, CalDAV)
│   ├── model/           # Event model and diff logic
│   ├── state/           # Database and config management
│   └── sync/            # Sync execution engine
├── node/                # Node.js MCP server
│   ├── server/          # Express server and MCP tools
│   └── static/          # Web UI files
├── database/            # Database schema
└── 0-docs/              # Comprehensive documentation

配置

Microsoft图形设置

1. 在Azure AD中注册应用程序
2. 为本地主机配置重定向URI
3. 请求 Calendars.ReadWrite 范围
4. 使用设备代码流进行身份验证

看 0-docs/03-implementation/02-step2-graph-connector.md 了解详情。

文档

综合文档 0-docs/:

• 概述：目的、限制、技术栈
• 建筑：系统设计和组件
• 实施：分步指南
• API 设计：MCP工具和HTTP端点
• 数据库：架构和存储详细信息

从以下内容开始： 0-docs/README.md

发展

该项目遵循严格的模块化准则：

• 每个文件不超过100行
• 每个模块的单一职责
• 明确区分关注点

测试

Python单元测试:

bash run_tests.sh

Windows Python测试:

# Run all Python tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ -v --cov=python --cov-report=html

剧作家E2E测试:

bash run_e2e_tests.sh

Windows E2E测试:

# Install Playwright browsers (first time only)
npx playwright install

# Run E2E tests
npx playwright test

# Run E2E tests with UI mode
npx playwright test --ui

看 tests/ Python测试和 tests-e2e/ 剧作家测试。

作者

巴巴克·班佩 — cocode.dk | 领英 |

许可证

阿帕奇-2.0 |©2026 科科德 |创建者： 巴巴克·班佩

看 许可证 文件以获取详细信息。

状态

第0阶段-MVP开发 ✅

• 核心数据库和状态管理
• Microsoft图形连接器
• 谷歌日历连接器
• iCloud CalDAV连接器
• 同步引擎（手动同步+预览）
• 带工具的MCP服务器
• 具有深色模式的全面web UI
• OAuth凭据管理

功能实现:

• ✅ CalDAV支持：完全通过iCloud连接器实现
• ✅ OAuth流用户界面：使用会话管理完成设备代码流
• ⚠️ 错误处理：已实现基本日志记录，重试逻辑需要开发
• ❌ 连续同步调度程序：数据库架构已就绪，调度程序模块尚未构建

接下来:

• 具有可配置间隔的连续同步调度器
• 具有指数退避和重试逻辑的高级错误处理
• 其他CalDAV提供商（Nextcloud等）
• 冲突解决策略