MCP Nextcloud Calendar

这是一个用于Nextcloud日历集成的Model Context Protocol (MCP)服务器。

功能

• 从Nextcloud获取日历
• 适合ADHD用户的组织功能
• 支持MCP协议（流式HTTP和传统HTTP+SSE）

使用方法

使用npx

最简单的方式是通过npx来使用这个包：

npx mcp-nextcloud-calendar

安装

对于开发或本地安装：

# 全局安装
npm install -g mcp-nextcloud-calendar

# 或者本地安装
npm install mcp-nextcloud-calendar

MCP客户端配置

要与MCP客户端（如Claude）一起使用，请在您的MCP客户端设置中添加以下配置：

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

指定版本

您可以指定一个特定版本的包：

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

配置

环境变量

服务器使用这些环境变量，其中可能有默认值：

变量	描述	默认值	是否必需
PORT	服务器端口	3001	否
SERVER_NAME	MCP服务器标识符	nextcloud-calendar-server	否
NODE_ENV	环境（开发/生产）	development	否
NEXTCLOUD_BASE_URL	您的Nextcloud服务器URL	-	是
NEXTCLOUD_USERNAME	您的Nextcloud用户名	-	是
NEXTCLOUD_APP_TOKEN	您的Nextcloud应用令牌	-	是
KEEP_ALIVE_INTERVAL	保持活动间隔（毫秒）	30000	否

开发设置

对于本地开发：

1. 克隆仓库
2. 安装依赖项：

npm install

3. 在项目根目录创建一个.env文件：

cp .env.example .env

4. 使用您的Nextcloud凭据编辑.env文件。

获取Nextcloud应用令牌

1. 登录到您的Nextcloud实例
2. 前往设置 → 安全 → 应用密码
3. 创建一个新的应用密码，例如命名为"MCP Calendar"
4. 将生成的令牌复制到您的.env文件中

开发

# 构建项目
npm run build

# 开发模式运行
npm run dev

# 运行测试
npm run test

# 运行代码检查
npm run lint

# 格式化代码
npm run format

API端点

• /mcp - 主要的MCP端点（流式HTTP传输）
• /sse 和 /messages - 传统的MCP端点（HTTP+SSE传输）
• GET /health - 健康检查端点
• GET /api/calendars - 列出所有日历

MCP工具

以下MCP工具已注册并可供客户端使用：

日历管理

工具	描述	参数
listCalendars	获取所有可访问的日历	无
createCalendar	创建新的日历	displayName（必需），color（可选），category（可选），focusPriority（可选）
updateCalendar	更新现有的日历	id（必需），displayName（可选），color（可选），category（可选），focusPriority（可选）
deleteCalendar	删除日历	id（必需）

⚠️ 权限警告：updateCalendar和deleteCalendar工具可能需要您Nextcloud实例中的特殊权限。日历操作受Nextcloud权限系统约束。

事件管理

工具	描述	参数
listEvents	获取日历中的事件	calendarId（必需），start（可选），end（可选）
getEvent	获取特定事件	calendarId（必需），eventId（必需）
createEvent	创建新的事件	calendarId（必需），summary（必需），start（必需），end（必需），description（可选），location（可选）
updateEvent	更新现有事件	calendarId（必需），eventId（必需），[加上要更新的任何事件属性]
deleteEvent	删除事件	calendarId（必需），eventId（必需）

已知问题和限制

注意：此包目前处于早期开发阶段（0.1.x）。未来的发布可能会更改API和工具，且不另行通知。

• 更新和删除日历的操作可能需要您Nextcloud实例中的特定权限。
• 对于特定Nextcloud错误代码的错误处理仍在改进中。
• 包含大量事件的大日历可能会遇到性能问题。

请在GitHub存储库中报告任何问题。

许可证

ISC