nextcloud-mcp-服务器

Name: nextcloud-mcp-服务器
Author: cbcoutinho

作者：cbcoutinho60 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

Nextcloud MCP 服务器

一个生产就绪的 MCP 服务器，用于连接 AI 助手到您的 Nextcloud 实例。

启用大型语言模型如 Claude、GPT 和 Gemini 通过安全 API 与您的 Nextcloud 数据进行交互。创建笔记、管理日历、组织联系人、处理文件等——所有这些都可以通过自然语言对话完成。

这是一个专为外部 MCP 客户端（如 Claude Code 和 IDE）设计的独立 MCP 服务器。它独立于 Nextcloud 运行（Docker、VM、Kubernetes 或本地），并提供跨 Nextcloud 应用程序的深度 CRUD 操作。

[!NOTE] 想要在 Nextcloud 内部使用 AI 功能？ Nextcloud 还提供了 Context Agent，它驱动了 Assistant 应用，并作为 ExApp 在 Nextcloud 内运行。参见 docs/comparison-context-agent.md 获取详细的使用场景比较。

快速开始

最快的方式是通过 Smithery 开始——无需 Docker 或自托管：

访问 Smithery 市场页面
点击“部署”并配置：
- Nextcloud URL：您的 Nextcloud 实例（例如，https://cloud.example.com）
- 用户名：您的 Nextcloud 用户名
- 应用密码：在 Nextcloud → 设置 → 安全 → 设备与会话中生成一个

[!NOTE] Smithery 以无状态模式运行，不支持语义搜索。要获得全部功能，请使用 Docker 或参见 ADR-016。

Docker (自托管)

要获得包括语义搜索在内的全部功能，请使用 Docker 运行：

# 1. 创建最小配置
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. 启动服务器
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. 测试连接
curl http://127.0.0.1:8000/health/ready

# 4. 连接到端点
http://127.0.0.1:8000/sse

# 或使用 --transport streamable-http
http://127.0.0.1:8000/mcp

下一步操作：

连接您的 MCP 客户端（Claude Desktop、IDEs、mcp dev 等）
查看 docs/installation.md 获取其他部署选项（本地、Kubernetes）

主要特性

90+ MCP 工具 - 覆盖 8 个 Nextcloud 应用程序的全面 API
MCP 资源 - 结构化数据 URI 用于浏览 Nextcloud 数据
语义搜索（实验性） - 可选向量驱动搜索（需要 Qdrant + Ollama）
文档处理 - 从 PDF、DOCX、图像中提取 OCR 和文本，带有进度通知
灵活部署 - Docker、Kubernetes（Helm）、VM 或本地安装
生产就绪认证 - 基本认证（推荐）或 OAuth2/OIDC（实验性）
多种传输方式 - 支持 SSE、HTTP 和 streamable-http

支持的应用程序

应用	工具	功能
笔记	7	全 CRUD、关键词搜索、语义搜索
日历	20+	事件、待办事项（任务）、重复事件、参与者、可用性
联系人	8	完整 CardDAV 支持、地址簿
文件（WebDAV）	12	文件系统访问、OCR/文档处理
看板	15	看板、堆栈、卡片、标签、分配
食谱	13	食谱管理、URL 导入（schema.org）
表格	5	Nextcloud 表格上的行操作
共享	10+	创建和管理共享
语义搜索	2+	笔记的向量搜索（实验性，需手动开启，需要基础设施）

希望看到另一个 Nextcloud 应用程序被支持？打开一个问题或贡献一个拉取请求！

认证

[!IMPORTANT] OAuth2/OIDC 是实验性的 并且需要对 user_oidc 应用程序进行手动补丁：

所需补丁：Bearer 令牌支持 (问题 #1221)

影响：没有补丁，大多数应用程序特定的 API 将因 401 错误而失败

建议：直到上游补丁合并，使用基本认证进行生产环境

查看 docs/oauth-upstream-status.md 获取补丁状态和解决方法。

推荐：使用应用特定密码的基本认证提供安全、生产就绪的认证。查看 docs/authentication.md 获取设置详情和 OAuth 配置。

认证模式

服务器支持两种认证模式：

单用户模式（BasicAuth）：

所有 MCP 客户端共享一组凭据
简单设置：环境变量中的用户名 + 应用密码
所有客户端以同一用户身份访问 Nextcloud
最适合：个人使用、开发、单用户部署

多用户模式（OAuth）：

每个 MCP 客户端使用自己的 Nextcloud 账户单独认证
每用户的范围和权限（客户端仅能看到他们授权的工具）
更安全：令牌过期，凭据从未与服务器共享
最适合：团队、多用户部署、具有多个用户的生产环境

查看 docs/authentication.md 获取详细设置说明。

语义搜索

服务器提供了一个实验性的 RAG 管道，以启用基于意义而非仅仅关键词的 语义搜索。这使得 MCP 客户端能够根据概念的语义相关性找到 Nextcloud 中的信息。例如，“神经网络”、“AI 模型”和“深度学习”被视为与“机器学习”相关的概念。

示例：

关键词搜索：查询“汽车”仅找到包含“汽车”的笔记
语义搜索：查询“汽车”也找到关于“汽车”、“车辆”、“轿车”、“运输”的笔记

这使自然语言查询成为可能，并帮助发现您 Nextcloud 笔记中的相关内容。

[!NOTE] 语义搜索是实验性的并且需手动开启：

默认禁用 (VECTOR_SYNC_ENABLED=false)

目前仅支持笔记应用（计划支持多应用）

需要额外的基础设施：向量数据库 + 嵌入服务

答案生成 (nc_semantic_search_answer) 需要 MCP 客户端采样支持

查看 docs/semantic-search-architecture.md 获取架构细节和 docs/configuration.md 获取设置说明。

文档

快速入门

安装 - Docker、Kubernetes、本地或 VM 部署
配置 - 环境变量和高级选项
认证 - 基本认证 vs OAuth2/OIDC 设置
运行服务器 - 启动、管理和故障排除

特性

应用文档 - 笔记、日历、联系人、WebDAV、看板、食谱、表格
文档处理 - OCR 和文本提取设置
语义搜索架构 - 实验性向量搜索（仅限笔记，需手动开启）
向量同步 UI 指南 - 浏览器界面用于语义搜索可视化和测试

高级主题

OAuth 架构 - 如何工作（实验性）
OAuth 快速入门 - 5 分钟 OAuth 设置
OAuth 设置指南 - 详细的 OAuth 配置
故障排除 - 常见问题及解决方案
与 Context Agent 的比较 - 使用每种方法的时间

示例

创建笔记

AI: "创建名为'Meeting Notes'的笔记，内容为今天的议程"
→ 使用 nc_notes_create_note 工具

导入食谱

AI: "从 https://www.example.com/recipe/chocolate-cake 导入食谱"
→ 使用 nc_cookbook_import_recipe 工具并提取 schema.org 元数据

安排会议

AI: "安排下周二下午 2 点的团队会议"
→ 使用 nc_calendar_create_event 工具

管理文件

AI: "创建名为'Project X'的文件夹并将所有 PDF 移动到那里"
→ 使用 nc_webdav_create_directory 和 nc_webdav_move 工具

语义搜索（实验性，需手动开启）

AI: "查找与机器学习概念相关的笔记"
→ 使用 nc_semantic_search 查找语义相似的笔记（需要 Qdrant + Ollama 设置）

注意：对于带有引文的 AI 生成答案，使用 nc_semantic_search_answer（需要具有采样支持的 MCP 客户端）。

贡献

欢迎贡献！

报告错误或请求功能：GitHub Issues
提交改进：Pull Requests
开发指南：CLAUDE.md

安全

此项目重视安全性：

生产就绪的基本认证，使用应用特定密码
OAuth2/OIDC 支持（实验性，需要上游补丁）
每用户的访问令牌
OAuth 模式下不存储凭据
定期安全评估