STARWARCLOUD STARWAR.AI
返回市场
nextcloud-mcp-服务器

nextcloud-mcp-服务器

作者：abdullahMASHUK3 星标更新：2025-09-03
安装使用来源：spider==github.com

项目介绍

<div align="center">

🌐 NextCloud MCP 服务器

npm 版本 下载量 许可证: MIT TypeScript

一个专业的模型上下文协议 (MCP) 服务器，用于无缝集成 NextCloud

赋予您的AI代理全面的NextCloud文件管理和共享能力

安装 • 快速开始 • 特性 • 文档 • 安全

</div>

🚀 特性

<div align="center">
📁 文件管理🔗 共享🔒 安全🛠️ 开发者体验
列表、上传、下载公共链接应用密码完整的 TypeScript 支持
创建目录用户/组共享环境变量全面测试
删除文件/文件夹密码保护安全认证专业文档
移动和重命名过期日期强制 HTTPS易于集成
</div>

✨ 关键能力

  • 🎯 14 项综合工具 - 完整的文件操作和共享管理
  • 🔐 增强的安全性 - 内置应用密码支持和最佳实践
  • 🏗️ 专业架构 - TypeScript 首选，完整的类型安全性
  • 📚 丰富的文档 - 详细的指南和示例
  • 🔄 WebDAV 集成 - 原生支持 NextCloud 协议
  • ⚡ 高性能 - 优化速度和可靠性
  • 🌍 通用兼容性 - 适用于任何 NextCloud 实例

📦 安装

从 NPM 安装（推荐）

# 全局安装以供 CLI 使用
npm install -g nextcloud-mcp-server

# 或在项目中本地安装
npm install nextcloud-mcp-server

从源码安装

git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install
npm run build

🚀 快速开始

1. 🔐 设置应用密码（推荐）

<details> <summary>点击展开安全设置说明</summary>

为了增强安全性，请创建一个专用的应用密码：

  1. 导航到 NextCloud 设置

    NextCloud → 设置 → 安全 → 应用密码

  2. 创建新应用密码

    • 输入名称：MCP 服务器
    • 点击“创建新应用密码”
    • 复制生成的密码：xxxxx-xxxxx-xxxxx-xxxxx-xxxxx

  3. 为什么使用应用密码？

    • ✅ 范围和权限有限
    • ✅ 可独立撤销
    • ✅ 不访问主账户
    • ✅ 可审计访问日志
</details>

2. ⚙️ 配置

# 复制环境模板
cp .env.example .env

编辑你的 .env 文件：

NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password-here  # 使用应用密码！

3. 🎮 使用 MCP 客户端

<details> <summary>Claude Desktop 配置</summary>

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "nextcloud": {
      "command": "nextcloud-mcp-server",
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}
</details> <details> <summary>直接使用</summary> 
# 运行 MCP 服务器
nextcloud-mcp-server

# 或使用 Node.js
node build/index.js
</details>

🛠️ 可用工具

📁 文件操作

<table> <tr> <td><strong>🔍 测试连接</strong></td> <td>测试与你的 NextCloud 服务器的连接</td> </tr> <tr> <td><strong>📋 列出文件</strong></td> <td>列出文件和目录及其元数据</td> </tr> <tr> <td><strong>📁 创建目录</strong></td> <td>在 NextCloud 中创建新目录</td> </tr> <tr> <td><strong>🗑️ 删除文件</strong></td> <td>删除文件或目录</td> </tr> <tr> <td><strong>⬆️ 上传文件</strong></td> <td>使用 base64 编码上传文件</td> </tr> <tr> <td><strong>⬇️ 下载文件</strong></td> <td>从 NextCloud 下载文件</td> </tr> <tr> <td><strong>🔄 移动文件</strong></td> <td>移动或重命名文件和目录</td> </tr> <tr> <td><strong>📄 复制文件</strong></td> <td>将文件和目录复制到新位置</td> </tr> <tr> <td><strong>🔍 搜索文件</strong></td> <td>按名称或内容搜索文件和目录</td> </tr> <tr> <td><strong>📚 获取文件版本</strong></td> <td>获取文件的历史版本</td> </tr> <tr> <td><strong>🔄 恢复文件版本</strong></td> <td>恢复文件的特定版本</td> </tr> </table>

🔗 共享操作

<table> <tr> <td><strong>🌐 创建共享</strong></td> <td>创建公共链接、用户或组共享</td> </tr> <tr> <td><strong>📤 列出共享</strong></td> <td>列出并筛选现有共享</td> </tr> <tr> <td><strong>🗑️ 删除共享</strong></td> <td>通过 ID 删除共享</td> </tr> </table>

📖 文档

🎯 工具示例

<details> <summary><strong>📋 列出文件</strong></summary> 
{
  "name": "list-files",
  "arguments": {
    "path": "/Documents"
  }
}

响应： 返回带有元数据（名称、大小、类型、修改日期）的文件数组

</details> <details> <summary><strong>⬆️ 上传文件</strong></summary> 
{
  "name": "upload-file",
  "arguments": {
    "remotePath": "/documents/report.pdf",
    "content": "JVBERi0xLjQK..."  // base64 编码的内容
  }
}
</details> <details> <summary><strong>🔄 移动文件</strong></summary> 
{
  "name": "move-file",
  "arguments": {
    "sourcePath": "/old-location/document.pdf",
    "destinationPath": "/new-location/document.pdf",
    "overwrite": false
  }
}

响应： 包含源和目标路径的确认消息

</details> <details> <summary><strong>📄 复制文件</strong></summary> 
{
  "name": "copy-file",
  "arguments": {
    "sourcePath": "/Documents/template.docx",
    "destinationPath": "/Projects/new-document.docx",
    "overwrite": true
  }
}

响应： 包含复制操作详情的确认消息

</details> <details> <summary><strong>🔍 搜索文件</strong></summary> 
{
  "name": "search-files",
  "arguments": {
    "query": "季度报告",
    "path": "/Documents",
    "limit": 20,
    "type": "file"
  }
}

响应： 匹配文件的数组，带有完整元数据

类型选项： file, directory, all

</details> <details> <summary><strong>📚 获取文件版本</strong></summary> 
{
  "name": "get-file-versions",
  "arguments": {
    "path": "/Documents/重要文档.pdf"
  }
}

响应： 文件版本的数组，带有时间戳、大小和用户信息

</details> <details> <summary><strong>🔄 恢复文件版本</strong></summary> 
{
  "name": "restore-file-version",
  "arguments": {
    "path": "/Documents/重要文档.pdf",
    "versionId": "1672531200"
  }
}

响应： 版本恢复的确认

</details> <details> <summary><strong>🌐 创建共享</strong></summary> 
{
  "name": "create-share",
  "arguments": {
    "path": "/Documents/演示文稿.pptx",
    "shareType": 3,
    "password": "secure123",
    "expireDate": "2024-12-31",
    "note": "团队评审共享"
  }
}

共享类型：

  • 0 - 用户共享
  • 1 - 组共享
  • 3 - 公共链接
  • 4 - 邮件共享
</details>

🏗️ 开发

<details> <summary>设置开发环境</summary> 
# 克隆并安装
git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install

# 开发命令
npm run dev          # 使用自动重新加载运行
npm run build        # 构建 TypeScript
npm run test         # 运行测试套件
npm run lint         # 检查代码质量
npm run format       # 格式化代码

项目结构：

src/
├── index.ts              # 主 MCP 服务器
├── services/
│   └── nextcloud.ts      # NextCloud API 客户端
├── types.ts              # TypeScript 定义
└── utils/                # 工具函数

__tests__/                # 测试套件
build/                    # 编译输出
</details>

🔒 安全

🛡️ 最佳实践

<div align="center">
✅ 应该❌ 不应该
使用应用密码使用主账户密码
存储在环境变量中硬编码凭据
使用 HTTPS URL使用 HTTP 连接
定期轮换密码保留旧密码
监控访问日志忽视安全事件
</div>

🔐 安全特性

  • 🔑 应用密码集成 - 专用身份验证令牌
  • 🌐 强制 HTTPS - 要求安全连接
  • 📝 环境变量 - 安全存储凭据
  • 🔍 错误处理 - 日志中不暴露凭据
  • 🛡️ 权限范围 - 有限的访问权限

⚠️ 安全检查清单

  • 创建并配置了应用密码
  • NextCloud 服务器启用了 HTTPS
  • 正确设置了环境变量
  • 将 .env 文件添加到 .gitignore
  • 定期安排密码轮换

License

MIT 许可证 - 查看 LICENSE 文件了解详情。

🤝 贡献

<div align="center">

我们欢迎贡献！

欢迎贡献者 欢迎 PR

</div> <details> <summary>🚀 <strong>如何贡献</strong></summary>
  1. 🍴 分叉仓库
  2. 🌿 创建功能分支 
    git checkout -b feature/amazing-feature
  3. 💻 进行更改
  4. ✅ 为新功能添加测试
  5. 🧪 运行测试套件 
    npm run test
npm run lint
  6. 📝 提交更改 
    git commit -m "✨ 添加精彩功能"
  7. 🚀 推送到你的分支 
    git push origin feature/amazing-feature
  8. 🔄 打开拉取请求
</details>

💡 贡献方式

<table> <tr> <td align="center">🐛<br><strong>报告错误</strong></td> <td align="center">✨<br><strong>提出功能建议</strong></td> <td align="center">📚<br><strong>编写文档</strong></td> <td align="center">🧪<br><strong>进行测试</strong></td> </tr> <tr> <td align="center">发现了一个问题？<br>报告它！</td> <td align="center">有一个想法？<br>分享它！</td> <td align="center">改进文档<br>和示例</td> <td align="center">添加测试并<br>提高覆盖率</td> </tr> </table>

💖 支持

<div align="center">

展示你的支持！ ⭐

如果这个项目对你有帮助，请考虑在 GitHub 上给它一个 ⭐！

GitHub stars GitHub forks

🗣️ 获取帮助

🔗 联系我们

GitHub npm

</div>

📜 许可证

<div align="center">

MIT 许可证 © 2024 Abdullah MASHUK

License: MIT

在此授予任何人免费获得此软件副本的许可...

📖 查看完整许可证

</div>

📈 更新日志

<details> <summary><strong>版本历史</strong></summary>

🎉 v1.0.3

  • 🎨 美化 README，采用专业格式和视觉增强
  • 📊 添加交互式表格、徽章和折叠部分
  • 👤 更新作者信息和 Git 配置
  • 🔗 增强导航，使用表情符号和更好的组织
  • ✨ 改善 npm 和 GitHub 用户的用户体验

🚀 v1.0.2

  • ✨ 增强文档和 README
  • 🔒 添加全面的安全指南
  • 📝 改进 TypeScript 定义
  • 🐛 修复错误和稳定性改进

🚀 v1.0.1

  • 📚 更新文档
  • 🔧 配置改进
  • 🛠️ 构建过程优化

🌟 v1.0.0

  • 🎊 初始发布
  • 📁 基本文件操作（列表、上传、下载、删除）
  • 🔗 共享管理（创建、列出、删除）
  • 🔧 TypeScript 实现
  • ✅ 全面的测试覆盖
  • 📖 完整文档
</details>
<div align="center">

由 ❤️ Abdullah MASHUK 制作

搭建 NextCloud 和 AI 助手之间的桥梁 🌉

使用 TypeScript 构建 由 MCP 提供

</div>