Nextcloud MCP服务器
](https://github.com/cbcoutinho/nextcloud-mcp-server/pkgs/container/nextcloud-mcp-server)
一个生产就绪的MCP服务器，将AI助手连接到Nextcloud实例。
使Claude、GPT和Gemini等大型语言模型能够通过安全的API与Nextcloud数据交互。创建笔记、管理日历、组织联系人、处理文件等等，所有这些都是通过自然语言对话完成的。
这是一个 专用独立MCP服务器 专为Claude Code和IDE等外部MCP客户端设计。它独立于Nextcloud（Docker、VM、Kubernetes或本地）运行，并在Nextcloud应用程序之间提供深度CRUD操作。
\[！注意\]
快速入门（Docker）
要获得包括语义搜索在内的完整功能，请使用Docker运行：
# 1. Create a minimal configuration
cat > .env \[！重要\]
> **OAuth2/OIDC是实验性的** 并且需要手动修补 `user_oidc` 应用程序：
>
> - **所需补丁**：不记名代币支持([第1221期](https://github.com/nextcloud/user_oidc/issues/1221))
> - **影响**：如果没有补丁，大多数特定于应用程序的API都会失败，出现401个错误
> - **推荐**：在合并上游补丁之前，使用Basic Auth进行生产
>
> 看 [docs/oauth-upstream-status.md](docs/oauth-upstream-status.md) 了解补丁状态和解决方法。
**推荐：** 使用特定于应用程序的密码的基本身份验证提供了安全的、生产就绪的身份验证。看 [docs/authentication.md](docs/authentication.md) 有关设置详细信息和OAuth配置。
### 身份验证模式
服务器支持四种身份验证模式：
**单用户（BasicAuth）：**
- 所有MCP客户端共享一组凭据
- 简单设置：环境变量中的用户名+应用程序密码
- 所有客户端都以同一用户身份访问Nextcloud
- 最适合：个人使用、开发、单用户部署
**多用户（基本认证传递）：**
- MCP客户端通过授权标头发送凭据
- 服务器传递到Nextcloud（默认情况下为无状态）
- 后台操作的可选离线访问(`ENABLE_MULTI_USER_BASIC_AUTH=true`)
- 最适合：没有OAuth基础架构的多用户设置
**多用户（OAuth）：**
- 每个MCP客户端都使用自己的Nextcloud帐户分别进行身份验证
- 每个用户的范围和权限（客户端只能看到他们授权的工具）
- 更安全：令牌过期，凭据从不与服务器共享
- 最适合：团队、多用户部署、多用户生产环境
- 需要：补丁 `user_oidc` 应用程序（实验）
**多用户（登录流v2）：**
- 使用Nextcloud的本地Login Flow v2获取每个用户的应用程序密码
- 无需OAuth补丁——与Nextcloud兼容
- 每个用户通过浏览器进行身份验证，服务器管理应用程序密码
- 最适合：无OAuth基础架构的多用户部署(`ENABLE_LOGIN_FLOW=true`)
- 实验：见 [ADR-022](docs/ADR-022-deployment-mode-consolidation.md) 详见
看 [docs/authentication.md](docs/authentication.md) 有关详细的设置说明。
## 语义搜索
服务器提供了一个实验性的RAG管道，以实现 _语义搜索_ 使MCP客户端能够基于以下内容在Nextcloud中查找信息 **意义** 而不仅仅是关键字。它理解“神经网络”、“人工智能模型”和“深度学习”是语义相关的概念，而不是只在出现这些确切的单词时才匹配“机器学习”。
**例子：**
- **关键词搜索**：查询“car”只找到包含“car”的笔记
- **语义搜索**：查询“car”还可以找到关于“汽车”、“车辆”、“轿车”、“交通工具”的注释
这支持自然语言查询，并有助于在Nextcloud笔记中发现相关内容。
> \[！注意\]
> **语义搜索是实验性的，可以选择加入：**
>
> - 默认情况下已禁用(`ENABLE_SEMANTIC_SEARCH=false`)
> - 目前仅支持Notes应用程序（计划支持多应用程序）
> - 需要额外的基础设施：矢量数据库+嵌入服务
> - 答案生成(`nc_semantic_search_answer`)需要MCP客户端采样支持
>
> 看 [docs/语义搜索架构.md](docs/semantic-search-architecture.md) 了解架构细节和 [docs/configuration.md](docs/configuration.md) 有关设置说明。
## 文档
### 入门指南
- **[安装](docs/installation.md)** -Docker、Kubernetes、本地或VM部署
- **[配置](docs/configuration.md)** -环境变量和高级选项
- **[认证](docs/authentication.md)** -基本身份验证与OAuth2/OIDC设置
- **[运行服务器](docs/running.md)** -启动、管理和故障排除
### 特性
- **[应用程序文档](docs/)** -笔记、日历、联系人、WebDAV、甲板、食谱、表格
- **[文档处理](docs/configuration.md#document-processing)** -OCR和文本提取设置
- **[语义搜索架构](docs/semantic-search-architecture.md)** -实验向量搜索（笔记、文件、新闻项目、卡片；选择加入）
- **[矢量同步UI指南](docs/user-guide/vector-sync-ui.md)** -用于语义搜索可视化和测试的浏览器界面
### 高级主题
- **[OAuth架构](docs/oauth-architecture.md)** -OAuth的工作原理（实验）
- **[OAuth快速入门](docs/quickstart-oauth.md)** -5分钟OAuth设置
- **[OAuth设置指南](docs/oauth-setup.md)** -详细的OAuth配置
- **[故障排除](docs/troubleshooting.md)** -常见问题和解决方案
- **[与上下文代理的比较](docs/comparison-context-agent.md)** -何时使用每种方法
## 示例
### 创建笔记
AI: "Create a note called 'Meeting Notes' with today's agenda" → Uses nc_notes_create_note tool
### 进口食谱
AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake" → Uses nc_cookbook_import_recipe tool with schema.org metadata extraction
### 安排会议
AI: "Schedule a team meeting for next Tuesday at 2pm" → Uses nc_calendar_create_event tool
### 管理文件
AI: "Create a folder called 'Project X' and move all PDFs there" → Uses nc_webdav_create_directory and nc_webdav_move tools
### 语义搜索（实验性，选择加入）
AI: "Find notes related to machine learning concepts" → Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)
**注：** 对于人工智能生成的带有引用的答案，请使用 `nc_semantic_search_answer` （需要具有采样支持的MCP客户端）。
## 贡献
欢迎投稿！
- 报告错误或请求功能：
- 提交改进： [拉取请求](https://github.com/cbcoutinho/nextcloud-mcp-server/pulls)
- 开发指南： [CLAUDE.md](CLAUDE.md)
## 安全
[](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)
这个项目非常重视安全：
- 具有应用程序特定密码的生产就绪基本身份验证
- OAuth2/OIDC支持（实验性，需要上游补丁）
- 每用户访问令牌
- OAuth模式下没有凭据存储
- 定期安全评估
发现安全问题？请私下向维护人员报告。
## 许可证
该项目根据AGPL-3.0许可证获得许可。看 [许可证](./LICENSE) 了解详情。
## 星迹
[](https://www.star-history.com/#cbcoutinho/nextcloud-mcp-server&Date)
## 参考文献
- [模型上下文协议](https://github.com/modelcontextprotocol)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [云端下一站](https://nextcloud.com/)