AI导哈

Nextcloud AI助手服务器

一个生产就绪的MCP服务器，将AI助手连接到您的Nextcloud实例，支持通过自然语言交互管理笔记、日历、联系人、文件等。

  • by No-Smoke
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 No-Smoke/nextcloud-mcp-comprehensive

使用说明

Nextcloud MCP服务器

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

使Claude、GPT和Gemini等大型语言模型能够通过安全的API与Nextcloud数据交互。创建笔记、管理日历、组织联系人、处理文件等等，所有这些都是通过自然语言对话完成的。

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

[！注意] 在Nextcloud中寻找AI功能？ Nextcloud还提供 上下文代理，它为Assistant应用程序提供动力，并在Nextcloud中作为ExApp运行。看 docs/comparison-context-agent.md 以获取用例的详细比较。

快速入门（Docker）

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

# 1. Create a minimal configuration
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. Start the server
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. Test the connection
curl http://127.0.0.1:8000/health/ready

# 4. Connect to the endpoint
http://127.0.0.1:8000/sse

# Or with --transport streamable-http
http://127.0.0.1:8000/mcp

Docker编写配置文件 （用于开发/测试）：

docker compose --profile single-user up -d       # Port 8000
docker compose --profile multi-user-basic up -d   # Port 8003
docker compose --profile oauth up -d              # Port 8001
docker compose --profile login-flow up -d         # Port 8004

下一步：

  • 连接您的MCP客户端（克劳德桌面、IDE、， mcp dev等等）
  • 看 docs/installation.md 其他部署选项（本地、Kubernetes）

主要特点

  • 90+MCP工具 -全面覆盖8个Nextcloud应用程序的API
  • MCP资源 -用于浏览Nextcloud数据的结构化数据URI
  • 语义搜索（实验） -可选矢量搜索笔记、文件、新闻项目和卡片（需要Qdrant+Ollama）
  • 文档处理 -从PDF、DOCX、带有进度通知的图像中提取OCR和文本
  • 灵活部署 -Docker、Kubernetes（Helm）、VM或本地安装
  • 生产就绪认证 -使用应用程序密码的基本身份验证（推荐）或OAuth2/OIDC（实验）
  • 多个传输 -SSE、HTTP和可流式传输的HTTP支持

支持的应用程序

应用程序 工具 功能
备注 7 全CRUD、关键字搜索、语义搜索
日历 20+ 事件、待办事项（任务）、定期事件、与会者、可用性
联系人 8 完全支持CardDAV，地址簿
文件（WebDAV） 12 文件系统访问、OCR/文档处理
甲板 15 板、堆、卡、标签、作业
食谱 13 配方管理，URL导入（schema.org）
表格 5 Nextcloud表上的行操作
共享 10+ 创建和管理股份
语义搜索 2+ 笔记、文件、新闻项目和卡片的矢量搜索（实验性、选择加入、需要基础设施）

想看到另一个支持Nextcloud的应用程序吗？ 打开一个问题 或者提交一个pull请求！

认证

[！重要] OAuth2/OIDC是实验性的 并且需要手动修补 user_oidc 应用程序：

  • 所需补丁：不记名代币支持(第1221期)
  • 影响：如果没有补丁，大多数特定于应用程序的API都会失败，出现401个错误
  • 推荐：在合并上游补丁之前，使用Basic Auth进行生产

看 docs/oauth-upstream-status.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/authentication.md 有关详细的设置说明。

语义搜索

服务器提供了一个实验性的RAG管道，以实现 语义搜索 使MCP客户端能够基于以下内容在Nextcloud中查找信息 意义 而不仅仅是关键字。它理解“神经网络”、“人工智能模型”和“深度学习”是语义相关的概念，而不是只在出现这些确切的单词时才匹配“机器学习”。

例子：

  • 关键词搜索：查询“car”只找到包含“car”的笔记
  • 语义搜索：查询“car”还可以找到关于“汽车”、“车辆”、“轿车”、“交通工具”的注释

这支持自然语言查询，并有助于在Nextcloud笔记中发现相关内容。

[！注意] 语义搜索是实验性的，可以选择加入：

  • 默认情况下已禁用(ENABLE_SEMANTIC_SEARCH=false)
  • 目前仅支持Notes应用程序（计划支持多应用程序）
  • 需要额外的基础设施：矢量数据库+嵌入服务
  • 答案生成(nc_semantic_search_answer)需要MCP客户端采样支持

看 docs/语义搜索架构.md 了解架构细节和 docs/configuration.md 有关设置说明。

文档

入门指南

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

特性

高级主题

示例

创建笔记

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客户端）。

贡献

欢迎投稿！

安全

这个项目非常重视安全：

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

发现安全问题？请私下向维护人员报告。

许可证

该项目根据AGPL-3.0许可证获得许可。看 许可证 了解详情。

星迹

参考文献

相关 MCP