NextCloud文件管理协议服务器

NextCloud MCP服务器

一个模型上下文协议（MCP）服务器，使Claude和其他AI助手能够与您的NextCloud实例进行交互。直接从您的AI对话中浏览文件、搜索内容、阅读文档和管理NextCloud存储。

特性

🔍 核心文件操作

• 列出文件：浏览包含详细元数据的目录
• 读取文件：查看文本文件内容
• 搜索文件：按名称或内容类型查找文件
• 文件简介：获取有关任何文件或文件夹的详细元数据

📝 文件管理

• 上传文件：添加新文件（文本或二进制）
• 创建文件夹：使用新目录进行组织
• 移动项目：重新定位文件和文件夹
• 复制项目：重复的文件和文件夹
• 删除项目：删除不需要的文件和文件夹

🎯 智能功能

• 多种响应格式（JSON和Markdown）
• 大文件的自动内容截断
• 人类可读的文件大小
• 全面的错误信息和可操作的指导
• 支持应用程序密码（推荐）

安装

1.安装依赖项

pip install -r requirements.txt

2.设置环境变量

创建一个 .env 文件或设置环境变量：

export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USERNAME="your_username"
export NEXTCLOUD_PASSWORD="your_app_password"

重要：强烈建议使用 应用程序密码 代替您的主密码：

1. 登录NextCloud web界面
2. 前往设置→ 安全
3. 滚动到“设备和会话”
4. 创建新的应用程序密码
5. 在中使用此应用程序密码 NEXTCLOUD_PASSWORD 变量

3.配置克劳德桌面

添加到您的 claude_desktop_config.json:

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

窗户： %APPDATA%\Claude\claude_desktop_config.json

Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nextcloud": {
      "command": "python",
      "args": ["/absolute/path/to/nextcloud_mcp.py"],
      "env": {
        "NEXTCLOUD_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

4.重新启动克劳德桌面

重新启动Claude Desktop以使更改生效。

用法示例

浏览您的文件

Show me my NextCloud files

搜索文档

Search my NextCloud for PDF files about "project plan"

读取文件

Read the file /Documents/notes.txt from NextCloud

上传文件

Create a new file in NextCloud at /Documents/meeting-notes.md with the content:
[your content here]

整理文件

Move /temp/report.pdf to /Documents/Reports/2024/report.pdf in NextCloud

可用工具

只读工具

修改工具

配置

环境变量

路径格式

• 路径应以开头 / 对于根目录
• 示例：
  • 根： /
  • 文档文件夹： /Documents
  • 嵌套文件： /Documents/Reports/2024/report.pdf

安全最佳实践

1. 使用应用程序密码：始终使用应用程序密码而不是主密码
2. 限制权限：可以在不更改主密码的情况下撤销应用程序密码
3. 环境变量：从不将凭据提交到版本控制
4. 仅限HTTPS：始终对NextCloud URL使用HTTPS

故障排除

身份验证错误

问题：“身份验证失败”消息

解决方案:

• 验证您的凭据是否正确
• 使用应用程序密码（不是您的主密码）
• 检查您的NextCloud URL是否正确
• 确保您拥有适当的访问权限

路径找不到

问题：“找不到路径”错误

解决方案:

• 检查路径拼写和区分大小写
• 确保父目录存在
• 使用正斜杠(/)不要反睫毛(\)
• 开始路径 / 对于根目录

连接问题

问题：超时或连接错误

解决方案:

• 验证NextCloud服务器是否可访问
• 检查防火墙和网络设置
• 确保NEXTCLOUD_URL包含协议(https://)
• 首先通过web浏览器测试访问权限

发展

运行测试

# Install dev dependencies
pip install -r requirements.txt

# Run the server
python nextcloud_mcp.py

项目结构

nextcloud-mcp/
├── nextcloud_mcp.py      # Main MCP server implementation
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── .env.example         # Environment variable template

WebDAV API参考

此服务器使用NextCloud的WebDAV API。关键端点：

• 文件操作： /remote.php/dav/files/{username}/
• WebDAV方法：PROPFIND、GET、PUT、MKCOL、DELETE、MOVE、COPY、SEARCH

有关更多信息，请参阅：

• NextCloud WebDAV文档

贡献

欢迎投稿！贡献：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

发布到PyPI

通过pip与社区分享：

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*

然后用户可以安装：

pip install mcp-nextcloud

与社区分享

提交至MCP注册中心

1. 使用以下代码创建GitHub存储库
2. 添加全面的文档
3. 创建评估测试
4. 使某人忍受某事:https://github.com/modelcontextprotocol/registry

创建npm包（可选）

为了更广泛地分发，您还可以创建TypeScript版本。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

• GitHub问题：报告错误和请求功能
• 文档：查看NextCloud的官方文档
• 社区：加入MCP Discord/论坛

更新日志

1.0.0版本（首次发布）

• 核心文件操作（列表、读取、搜索、信息）
• 文件管理（上传、创建、移动、复制、删除）
• JSON和Markdown输出格式
• 全面的错误处理
• 应用密码支持
• 大文件的内容截断

作者

内置❤️ 对于MCP社区

准备好开始了吗？ 按照上述安装步骤，开始使用AI管理NextCloud文件！