Nextcloudmcp

Nextcloud MCP 服务

一个功能全面的 Nextcloud 集成模型上下文协议（MCP）服务，为 AI Agent 提供安全访问 Nextcloud 文件管理、共享、用户管理和系统监控功能的能力。

功能

🗂️ 文件管理

• WebDAV 操作：列出、上传、下载、删除、移动和复制文件及文件夹
• 目录导航：按可配置的深度浏览目录结构
• 二进制文件支持：通过 Base64 编码处理文本和二进制文件
• 创建文件夹：在你的 Nextcloud 实例中创建新目录

🔗 共享管理

• 创建共享：创建用户、群组、公开和电子邮件共享
• 共享配置：设置权限、密码、到期日期和备注
• 共享监控：列出并监控所有现有共享
• 更新共享：修改现有共享设置
• 删除共享：移除不再需要的共享

👥 用户管理

• 用户管理：创建、读取、更新和删除用户（需要管理员权限）
• 群组管理：创建群组并管理群组成员
• 用户详情：访问全面的用户信息，包括配额和偏好设置
• 批量操作：高效处理多个用户和群组

🔧 系统监控

• 服务状态：监控 Nextcloud 服务运行状况和版本信息
• 功能：访问服务功能和配置详情
• 安全审计：内置安全审计工作流

📋 工作流提示词

• 备份工作流：自动化文件备份流程
• 共享管理：全面的共享工作流
• 用户管理：分步用户管理流程
• 文件整理：智能文件分类和整理
• 安全审计：自动化安全评估流程

安装

前提条件

• Node.js 18+
• npm 或 yarn
• 可通过 API 访问的 Nextcloud 服务
• 有效的 Nextcloud 用户凭据

设置

1. 克隆并安装依赖：

git clone https://github.com/mirekdlugosz/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install

2. 配置环境变量： 在根目录中创建 .env 文件：

NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-password-or-app-password

安全提示：建议使用应用密码，而不是主密码。请在 Nextcloud“设置”→“安全”→“设备与会话”中生成应用密码。

3. 构建项目：

npm run build

4. 测试服务：

npm start

在 Claude Desktop 中使用

将以下配置添加到 Claude Desktop 配置文件中：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/path/to/nextcloud-mcp-server/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-password-or-app-password"
      }
    }
  }
}

可用工具（共 37 个）

文件操作（7 个）

• nextcloud_list_files - 列出文件和文件夹
• nextcloud_upload_file - 将文件上传到 Nextcloud
• nextcloud_download_file - 从 Nextcloud 下载文件
• nextcloud_delete_file - 删除文件或文件夹
• nextcloud_move_file - 移动或重命名文件/文件夹
• nextcloud_copy_file - 复制文件或文件夹
• nextcloud_create_folder - 创建新文件夹

共享管理（4 个）

• nextcloud_list_shares - 列出所有共享
• nextcloud_create_share - 创建新共享
• nextcloud_update_share - 更新现有共享
• nextcloud_delete_share - 删除共享

用户管理（7）

• nextcloud_list_users - 列出所有用户
• nextcloud_get_user - 获取用户详情
• nextcloud_create_user - 创建新用户
• nextcloud_update_user - 更新用户信息
• nextcloud_delete_user - 删除用户
• nextcloud_enable_user - 启用已停用的用户账户 ⭐ NEW
• nextcloud_disable_user - 停用用户账户（保留数据）⭐ NEW

群组管理（6）

• nextcloud_list_groups - 列出所有群组
• nextcloud_create_group - 创建新群组
• nextcloud_delete_group - 删除群组 ⭐ NEW
• nextcloud_add_user_to_group - 将用户添加到群组
• nextcloud_remove_user_from_group - 将用户从群组中移除
• nextcloud_get_group_users - 获取群组中的所有用户 ⭐ NEW

系统信息（3）

• nextcloud_get_server_status - 获取服务状态
• nextcloud_get_capabilities - 获取服务功能
• nextcloud_test_connection - 测试连接并验证凭据

评论（3）

• nextcloud_list_comments - 列出文件的评论
• nextcloud_add_comment - 为文件添加评论
• nextcloud_delete_comment - 删除文件的评论

本地文件管理（5）

• nextcloud_download_to_local - 将文件下载到本地文件夹，供 Claude 直接访问
• nextcloud_list_local_files - 列出本地下载文件夹中的文件
• nextcloud_delete_local_file - 删除本地文件夹中的文件
• nextcloud_upload_from_local - 将本地文件夹中的文件上传到 Nextcloud
• nextcloud_get_downloads_path - 获取下载文件夹的路径

活动监控（2）⭐ NEW CATEGORY

• nextcloud_list_activities - 列出近期活动（上传、分享、下载等）
• nextcloud_get_activity_types - 获取可用的活动类型和筛选条件

🆕 最新更新（2025-08-06）

新增工具：

1. nextcloud_get_group_users - 获取指定群组中的所有用户
2. nextcloud_delete_group - 从 Nextcloud 中删除群组
3. nextcloud_list_activities - 监控 Nextcloud 活动（NEW CATEGORY）
4. nextcloud_get_activity_types - 获取可用的活动筛选条件
5. nextcloud_enable_user - 启用已停用的用户账户 ⭐ LATEST
6. nextcloud_disable_user - 停用用户账户（保留数据）⭐ LATEST

新增功能：

• 完整的用户管理：涵盖完整生命周期，包括启用和停用操作
• 完整的群组管理：现已支持列出群组成员和删除群组
• 活动监控：跟踪文件上传、下载、分享、用户操作和安全事件
• 增强安全性：无需丢失数据即可临时停用账户
• 提升用户体验：通过 7 个类别中的 37 个工具实现更出色的组织管理

可用资源

• nextcloud://files - 根目录文件列表
• nextcloud://shares - 所有共享概览
• nextcloud://users - 所有用户列表
• nextcloud://groups - 所有群组列表
• nextcloud://status - 服务状态信息
• nextcloud://capabilities - 服务功能

可用提示词

• backup_files - 创建全面的备份工作流
• share_management - 使用详细选项管理文件共享
• user_administration - 完整的用户管理工作流
• file_organization - 使用智能分类整理文件
• security_audit - 对共享和权限执行安全审计

本地文件管理系统

此服务包含高效的本地文件管理系统，让 Claude 可以直接处理文件：

工作原理：

1. 下载到本地：将文件从 Nextcloud 下载到本地 downloads/ 文件夹
2. 直接访问：Claude 可以使用标准文件操作直接访问这些文件
3. 高效处理：处理大文件时无需进行 base64 编码或解码
4. 上传回去：可以将修改后的文件上传回 Nextcloud

优势：

• 性能：处理大型文件时，比 Base64 编码快得多
• 内存高效：无需将整个文件以 Base64 格式加载到内存中
• Claude 集成：Claude 可以使用标准文件工具读取、编辑和处理文档
• 工作流灵活性：下载 → 处理 → 上传工作流

工作流示例：

1. Download PDF from Nextcloud to local folder
2. Claude reads and analyzes the PDF directly
3. Claude creates a summary or modified version
4. Upload the new file back to Nextcloud

API 兼容性

此 MCP 服务支持 Nextcloud API 28.0+，并兼容：

• WebDAV API - 用于文件操作
• OCS API v1/v2 - 用于共享和用户管理
• 状态 API - 用于服务监控
• 评论 API - 用于文件评论

安全注意事项

• 应用密码：始终使用应用密码，而不是主账户密码
• 权限：某些操作需要管理员权限
• 网络安全：确保 Nextcloud 连接使用 HTTPS
• 访问控制：此服务遵循 Nextcloud 内置的访问控制
• 审计跟踪：Nextcloud 会记录所有操作

错误处理

此服务提供全面的错误处理，涵盖：

• 网络连接问题
• 身份验证失败
• 权限被拒绝错误
• 文件未找到错误
• 参数无效
• Nextcloud API 错误

开发

构建

npm run build

开发模式

npm run dev

代码检查

npm run lint
npm run lint:fix

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

1. 查看 Nextcloud API 文档
2. 查看 MCP 服务日志中的错误消息
3. 确保可以访问你的 Nextcloud 实例，且凭据正确
4. 确认你的用户对要执行的操作拥有必要的权限