MCP Nextcloud Calendar

MCP Nextcloud Calendar

用于集成 Nextcloud Calendar 的 Model Context Protocol（MCP）服务。

功能

• 从 Nextcloud 获取日历
• 适合 ADHD 用户的整理功能
• 支持 MCP 协议（Streamable HTTP 和 Legacy HTTP+SSE）

用法

使用 npx

使用此软件包最简单的方式是通过 npx：

npx mcp-nextcloud-calendar

安装

用于开发或本地安装：

# Install globally
npm install -g mcp-nextcloud-calendar

# Or install locally
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", "[email protected]"],
      "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	保持活动间隔（ms）	30000	否

开发环境设置

用于本地开发：

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

npm install

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

cp .env.example .env

4. 在 .env 文件中填写你的 Nextcloud 凭据。

获取 Nextcloud 应用令牌

1. 登录你的 Nextcloud 实例
2. 前往 Settings → Security → App Passwords
3. 创建一个新的应用密码，并命名为类似 “MCP Calendar” 的名称
4. 将生成的令牌复制到你的 .env 文件中

开发

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm run test

# Run linting
npm run lint

# Format code
npm run format

API 端点

• /mcp - 主要 MCP 端点（Streamable 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