Nextcloud MCP 服务器

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

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

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

[!NOTE] 正在寻找 Nextcloud 内部的 AI 功能？ Nextcloud 还提供了 Context Agent，它为 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 Compose 配置文件（用于开发/测试）：

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 客户端（Claude Desktop、IDE、mcp dev 等）

• 有关其他部署选项（本地、Kubernetes），请参阅 docs/installation.md

Related MCP server: Nextcloud MCP Server

主要功能

• 90+ MCP 工具 - 涵盖 8 个 Nextcloud 应用的全面 API 支持

• MCP 资源 - 用于浏览 Nextcloud 数据的结构化数据 URI

• 语义搜索（实验性） - 可选的基于向量的笔记、文件、新闻条目和 Deck 卡片搜索（需要 Qdrant + Ollama）

• 文档处理 - 带有进度通知的 PDF、DOCX、图像的 OCR 和文本提取

• 灵活部署 - Docker、Kubernetes (Helm)、虚拟机或本地安装

• 生产就绪的身份验证 - 使用应用密码的基本身份验证（推荐）或 OAuth2/OIDC（实验性）

• 多种传输方式 - 支持 SSE、HTTP 和流式 HTTP

支持的应用

想要支持其他 Nextcloud 应用？提交一个 issue 或提交拉取请求！

身份验证

[!IMPORTANT] OAuth2/OIDC 是实验性的，需要手动修补 user_oidc 应用：

• 必需补丁：Bearer 令牌支持 (issue #1221)

• 影响：如果没有补丁，大多数特定于应用的 API 将返回 401 错误

• 建议：在合并上游补丁之前，生产环境请使用基本身份验证

有关补丁状态和解决方法，请参阅 docs/oauth-upstream-status.md。

推荐：使用应用专用密码的基本身份验证可提供安全、生产就绪的身份验证。有关设置详情和 OAuth 配置，请参阅 docs/authentication.md。

身份验证模式

服务器支持四种身份验证模式：

单用户 (BasicAuth)：

• 所有 MCP 客户端共享一组凭据

• 设置简单：环境变量中的用户名 + 应用密码

• 所有客户端以同一用户身份访问 Nextcloud

• 适用场景：个人使用、开发、单用户部署

多用户 (BasicAuth 透传)：

• MCP 客户端通过 Authorization 标头发送凭据

• 服务器将其透传给 Nextcloud（默认无状态）

• 可选的后台操作离线访问 (ENABLE_MULTI_USER_BASIC_AUTH=true)

• 适用场景：没有 OAuth 基础设施的多用户设置

多用户 (OAuth)：

• 每个 MCP 客户端使用各自的 Nextcloud 账户单独进行身份验证

• 基于用户的范围和权限（客户端只能看到其被授权使用的工具）

• 更安全：令牌会过期，凭据永远不会与服务器共享

• 适用场景：团队、多用户部署、具有多个用户的生产环境

• 要求：修补 user_oidc 应用（实验性）

多用户 (登录流程 v2)：

• 使用 Nextcloud 原生的登录流程 v2 获取每个用户的应用密码

• 无需 OAuth 补丁 — 可与标准 Nextcloud 一起使用

• 每个用户通过浏览器进行身份验证，服务器管理应用密码

• 适用场景：没有 OAuth 基础设施的多用户部署 (ENABLE_LOGIN_FLOW=true)

• 实验性：详情请参阅 ADR-022

有关详细的设置说明，请参阅 docs/authentication.md。

语义搜索

服务器提供了一个实验性的 RAG 管道，以实现语义搜索，使 MCP 客户端能够基于含义而非仅仅关键词在 Nextcloud 中查找信息。它不仅能在出现完全匹配词时找到“机器学习”，还能理解“神经网络”、“AI 模型”和“深度学习”是语义相关的概念。

示例：

• 关键词搜索：查询“汽车”仅能找到包含“汽车”的笔记

• 语义搜索：查询“汽车”也能找到关于“轿车”、“车辆”、“交通工具”的笔记

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

[!NOTE] 语义搜索是实验性的，需要选择性加入：

• 默认禁用 (ENABLE_SEMANTIC_SEARCH=false)

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

• 需要额外基础设施：