JinDaGe - mcp-nextcloud-calendar MCP Details

article

README

🚀 MCP Nextcloud Calendar

MCP Nextcloud Calendar 是一个用于集成 Nextcloud 日历的模型上下文协议（MCP）服务器，它能从 Nextcloud 中获取日历信息，并提供对 ADHD 友好的组织功能，同时支持 MCP 协议。

🚀 快速开始

你可以使用 npx 快速使用该包：

npx mcp-nextcloud-calendar

✨ 主要特性

从 Nextcloud 获取日历信息。
具备对 ADHD 友好的组织功能。
支持 MCP 协议（可流式传输的 HTTP 和传统的 HTTP+SSE）。

📦 安装指南

全局安装

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，非必需 |

开发设置

本地开发步骤

克隆仓库。
安装依赖：

npm install

cp .env.example .env

使用你的 Nextcloud 凭证编辑 .env 文件。

获取 Nextcloud 应用令牌

登录你的 Nextcloud 实例。
转到设置 → 安全 → 应用密码。
创建一个名为“MCP Calendar”的新应用密码。
将生成的令牌复制到你的 .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 工具

日历管理

| 工具 | 描述 | 参数 | |------|-------------|------------| | 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（必需） |

📄 许可证

本项目采用 ISC 许可证。

⚠️ 重要提示

此包目前处于早期开发阶段（0.1.x）。API 和工具可能会在未来版本中无通知更改。

💡 使用建议

更新和删除日历操作可能需要你的 Nextcloud 实例中的特定权限。

针对特定 Nextcloud 错误代码的错误处理仍在改进中。

包含大量事件的大型日历可能会出现性能问题。

如果你遇到任何问题，请在 GitHub 仓库中报告。

mcp-nextcloud-calendar