MCP Twake

麦克特沃克·戴夫

](https://www.npmjs.com/package/mcp-twake-dav)  ](https://nodejs.org/)

MCP服务器 醒来 --将您的主权数字工作场所与任何兼容MCP的人工智能助手集成

Twake Calendar

概述

mcp-twake-dav是一个模型上下文协议（mcp）服务器，它将任何兼容mcp的AI助手（Claude Desktop、Claude CLI等）连接到您的CalDAV日历和CardDAV联系人。与基于SabreDAV的服务器兼容，包括Twake、Nextcloud和其他CalDAV/CardDAV实现。

主要优势：

• 您的数据保留在您自己的服务器上——主权基础设施
• 可与任何兼容MCP的AI助手配合使用
• 完全控制日历和联系人数据——读写
• 可通过npm安装——无需本地构建
• 仅支持HTTPS的安全连接（用于开发的本地主机除外）

特性

日历读取工具：

• get_next_event -查找您的下一次会议
• get_todays_schedule -查看今天安排的所有活动
• get_events_in_range -获取日期范围内的事件（自然语言：“本周”、“下个月”等）
• search_events -按关键字或与会者姓名搜索事件
• list_calendars -列出所有可用日历
• check_availability -查看一段时间内的忙/闲可用性

日历编写工具：

• create_event -创建新的日历事件（可选重复）
• update_event -更新现有事件（部分更新、单次编辑）
• delete_event -按UID删除事件（或单次重复事件）
• add_alarm -为事件添加提醒（自然语言：“15分钟”、“1小时”、“一天”）
• remove_alarm -从事件中删除提醒

邀请管理：

• list_invitations -列出等待您回复的待定日历邀请
• respond_to_invitation -接受、拒绝或暂时接受邀请

联系阅读工具：

• search_contacts -按姓名或组织搜索联系人
• get_contact_details -获取特定联系人的完整详细信息
• list_contacts -列出所有联系人（最多30个）
• list_addressbooks -列出所有可用的通讯簿

联系人写入工具：

• create_contact -创建新联系人
• update_contact -更新现有联系人（支持部分更新）
• delete_contact -按UID删除联系人

高级功能：

• 事件状态显示（已取消，明确标记暂定事件）
• 与会者参与状态（已接受、已取消、暂定、需要采取行动）
• 重复事件扩展（具有安全限制的RRULE支持）
• 单次事件编辑（修改或删除重复事件的单个事件）
• VALARM提醒管理（使用自然语言触发器添加/删除警报）
• RFC 6638调度收件箱支持（列出和响应邀请）
• 多日历和多地址簿搜索
• 基于CTag的缓存可提高性能
• 自然语言日期解析（由chrono节点提供支持）
• 用于故障排除的AI友好错误消息
• 跨事件和联系人进行不区分大小写的搜索
• 解析-修改-序列化更新（保留VALARM、X属性、ATTENDEE等）
• MCP工具注释（readOnlyHint、destructiveHint、openWorldHint）

先决条件

• Node.js >= 18.0.0
• CalDAV/CardDAV服务器 -SabreDAV兼容服务器，例如：

- Twake - 云端下一站 - OwnCloud - SOGo - DAVical - iCloud（有限支持）

• 需要HTTPS -您的CalDAV/CardDAV服务器必须使用HTTPS（用于开发的本地主机除外）
• MCP兼容AI助手 -Claude Desktop、Claude CLI或任何MCP客户端

安装

通过npx（推荐-无需安装）：

npx mcp-twake-dav

全局安装：

npm install -g mcp-twake-dav
mcp-twake-dav

来源（开发）：

git clone https://github.com/mmaudet/mcp-twake-dav.git
cd mcp-twake-dav
npm install
npm run build

快速设置（推荐）

配置mcp-twake-dav的最简单方法是使用交互式设置向导：

npx mcp-twake-dav setup

向导将：

1. 询问您的CalDAV/CardDAV服务器URL
2. 询问您的身份验证方法和凭据
3. 测试连接并发现您的日历和通讯簿
4. 允许您选择默认日历和通讯簿
5. 生成配置并将其写入Claude Desktop配置文件（可选）

示例会话：

  mcp-twake-dav Setup Wizard
  ───────────────────────────
  This wizard will configure mcp-twake-dav for your agent.

CalDAV/CardDAV server URL (e.g., https://dav.example.com): https://dav.linagora.com

Authentication method:
  1. Basic (username/password)
  2. Bearer token (JWT)
Choose [1-2]: 1
Username: user@example.com
Password:

Testing connection...

  Connected successfully!
  Found 4 calendar(s) and 2 address book(s).

Select default calendar:
  1. My Calendar
  2. Shared Calendar
  3. (All)
Choose [1-3]: 1

--- MCP Server Configuration ---

{
  "mcpServers": {
    "mcp-twake-dav": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.linagora.com",
        "DAV_USERNAME": "user@example.com",
        "DAV_PASSWORD": "********",
        "DAV_DEFAULT_CALENDAR": "My Calendar"
      }
    }
  }
}

Write configuration to config file? [Y/n]: y

  Added "mcp-twake-dav" in claude_desktop_config.json

Setup complete! Restart your agent to apply changes.

配置

环境变量

基本身份验证（默认）

标准用户名/密码验证。 DAV_AUTH_METHOD 可以省略（默认为 basic).

持有者令牌

JWT承载令牌，发送方式为 Authorization: Bearer .

可选的

安全说明： 强制使用HTTPS以防止凭据暴露。仅 localhost 和 127.0.0.1 出于开发目的，允许通过HTTP。

Claude桌面配置

要将mcp-twake-dav与Claude Desktop一起使用，请将以下内容添加到您的Claude Desktop配置文件中：

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

配置（基本身份验证）：

{
  "mcpServers": {
    "twake": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.example.com",
        "DAV_USERNAME": "user@example.com",
        "DAV_PASSWORD": "your-password",
        "DAV_DEFAULT_CALENDAR": "My Calendar",
        "DAV_DEFAULT_ADDRESSBOOK": "My Contacts"
      }
    }
  }
}

配置（承载令牌）：

{
  "mcpServers": {
    "twake": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.example.com",
        "DAV_AUTH_METHOD": "bearer",
        "DAV_TOKEN": "your-jwt-token",
        "DAV_DEFAULT_CALENDAR": "My Calendar",
        "DAV_DEFAULT_ADDRESSBOOK": "My Contacts"
      }
    }
  }
}

DAV_DEFAULT_CALENDAR 和 DAV_DEFAULT_ADDRESSBOOK 是可选的。设置后，默认情况下，工具仅查询指定的日历/通讯簿。使用 "all" 作为覆盖和搜索所有日历或地址簿的工具参数。

更新配置后，重新启动Claude Desktop以使更改生效。

用法示例

配置后，您可以向Claude自然语言询问有关日历和联系人的问题：

日历查询：

• “我的下一次会议是什么？”
• “今天我的日历上有什么？”
• “显示我本周的日程安排”
• “下个月我有什么会议？”
• “我什么时候和皮埃尔见面？”
• “查找有关预算的所有会议”
• “向我展示玛丽作为与会者的活动”
• “我明天下午有空吗？”
• “我本周第一个可用的45分钟时段是什么？”

日历管理：

• “明天下午2点与皮埃尔会面”
• “将我下午3点的会议改为下午4点”
• “删除团队同步事件”
• “每周一上午9点添加一次每周站立”
• “为我的牙医预约添加15分钟提醒”
• “从明天的会议中删除提醒”
• “仅将周二的站立移至上午10点”（单次）
• “仅取消周五的团队会议”（单次）

邀请管理：

• “我有任何待定的邀请吗？”
• “接受团队会议邀请”
• “拒绝电话会议”
• “暂时接受午餐会”

联系方式查询：

• “玛丽的电子邮件地址是什么？”
• “给我看皮埃尔的联系方式”
• “查找在LINAGORA工作的联系人”
• “列出我的所有联系人”
• “搜索名为Martin的联系人”
• “我有什么通讯录？”

联系人管理：

• “通过电子邮件为Jean Dupont创建联系人jean@example.com"
• “更新玛丽的电话号码”
• “删除联系人old-employee@example.com"

可用工具

故障排除

常见问题及解决方法

1.“配置验证失败”/缺少环境变量

• 问题： 所选身份验证方法缺少所需的环境变量
• 解决方案： 对于基本身份验证（默认）：set DAV_URL, DAV_USERNAME, DAV_PASSWORD.对于承载身份验证：set DAV_URL, DAV_AUTH_METHOD=bearer, DAV_TOKEN

2.“身份验证失败”/401未经授权

• 问题： 凭据或令牌无效
• 解决方案： 对于基本身份验证：验证DAV_用户名和DAV_密码。对于承载身份验证：验证DAV_TOKEN是否有效且未过期

3.“找不到服务器”/DNS解析错误

• 问题： 无法解析DAV_URL主机名
• 解决方案： 检查DAV_URL的拼写。确保您的服务器可以从网络访问。尝试在web浏览器中访问该URL

4.“连接超时”/网络超时

• 问题： 服务器无法访问或没有响应
• 解决方案： 验证您的CalDAV/CardDAV服务器是否联机。检查防火墙设置。确保您已与服务器建立网络连接

5.“URL必须使用HTTPS”/SSL证书错误

• 问题： 尝试HTTP连接（不安全）或SSL证书无效
• 解决方案： 在DAV_URL中使用HTTPS（例如。， https://dav.example.com).对于在本地主机上的开发，请使用 http://localhost 或 http://127.0.0.1。如果使用自签名证书，则必须使用有效的证书进行生产

6.“SSL证书错误”/证书验证失败

• 问题： 服务器上的自签名或无效SSL证书
• 解决方案： 使用来自可信证书颁发机构的有效SSL证书。生产环境中不支持自签名证书

7.“未找到日历”/“未找到通讯簿”

• 问题： 身份验证成功，但没有可用资源
• 解决方案： 验证您的帐户是否配置了CalDAV日历或CardDAV地址簿。检查您在CalDAV/CardDAV服务器上的权限。尝试通过服务器的web界面访问日历/联系人

8.克劳德桌面未显示工具/工具不可用

• 问题： MCP服务器未加载或配置错误
• 解决方案： 更改配置文件后重新启动Claude Desktop。验证配置文件路径是否适用于您的操作系统。确保 npx 在您的PATH中可用。查看Claude Desktop日志中的错误消息

9.“找不到模块”/模块解析错误

• 问题： 未安装包或缺少生成目录（从源代码运行时）
• 解决方案： 使用 npx -y mcp-twake-dav （推荐）或者，如果从源代码运行，则运行 npm run build 编译TypeScript

10.本地主机上的连接被拒绝

• 问题： 开发服务器未运行或端口错误
• 解决方案： 对于开发，请确保您的CalDAV/CardDAV服务器在本地主机上运行。验证DAV_URL中的端口号（例如。， http://localhost:8080)

发展

对于从源代码工作的贡献者：

git clone https://github.com/mmaudet/mcp-twake-dav.git
cd mcp-twake-dav
npm install
npm run build    # compile TypeScript
npm test         # run tests
npm run dev      # watch mode (auto-rebuild on file changes)

服务器使用MCP stdio传输，并通过stdin/stdout上的JSON-RPC进行通信。

建筑

mcp twake-dav采用分层架构构建：

1. 配置层 -基于Zod的环境变量验证，具有快速失败行为和HTTPS强制
2. 测井层 -配置用于stderr输出的引脚记录器（防止MCP stdio传输中的stdout污染）
3. CalDAV/CardDAV客户端层 -CalDAV和CardDAV的双tsdav客户端，具有发现、多方法身份验证（基本、承载）和连接验证功能
4. 基础设施层 -具有指数退避和抖动的重试逻辑，基于CTag的缓存用于性能优化
5. 服务层 -CalendarService和AddressBookService，具有资源获取和缓存管理功能
6. 转换层 -基于iCalendar和vCard格式的iCal.js解析、时区规范化、RRULE扩展、解析-修改-序列化更新
7. MCP工具层 -20个MCP工具，提供日历和联系人读/写功能，支持自然语言和工具注释
8. 入口点 -使用stdio传输初始化MCP服务器

关键设计决策：

• ESM模块 .js 导入扩展（MCP SDK要求）
• 被动缓存设计（服务检查 isCollectionDirty，不是缓存驱动的获取）
• AI友好的错误格式化（“出了什么问题”+“如何修复”模式）
• 解析-修改-序列化更新（保留VALARM、X属性、ATTENDEE参数）
• 用于AI客户端的MCP工具注释（readOnlyHint、destructiveHint、openWorldHint）

许可证

该项目根据 GNU Affero通用公共许可证v3.0（AGPL-3.0）.

请参阅 许可证 文件以获取详细信息。

版权所有（c）2026利纳戈拉

贡献

欢迎投稿！请阅读我们的 贡献指南 有关开发工作流、代码风格和pull请求过程的详细信息。

支持

对于问题、疑问或功能请求，请在GitHub存储库上打开问题。

如需商业支持或咨询，请联系LINAGORA： .