Nextcloud MCP Server

Nextcloud MCP 服务

可用于生产环境的 MCP 服务，可将 AI 助手连接到你的 Nextcloud 实例。

通过安全的 API，让 Claude、GPT 和 Gemini 等大模型与 Nextcloud 数据交互。通过自然语言对话创建笔记、管理日历、整理联系人、处理文件等。

这是一个专用的独立 MCP 服务，面向 Claude Code 和 IDE 等外部 MCP 客户端。它独立于 Nextcloud 运行（可使用 Docker、VM、Kubernetes 或本地环境），并可对 Nextcloud 应用执行深入的增删改查操作。

说明

**想在 Nextcloud 内部使用 AI 功能？**你可以将 Nextcloud 自带的助手连接到此服务——请参阅下方的 在 Nextcloud 内使用 AI。

提示

不想自行托管？Astrolabe Cloud 是此 MCP 服务的托管服务，面向希望使用后台同步和语义搜索等高级功能、又不想自行运维基础设施的个人和团队。该服务目前仍在开发中——请在落地页注册，加入早期用户名单。

快速开始

使用 uvx 在本地运行服务（无需安装）：

NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
  uvx nextcloud-mcp-server run --transport stdio

也可以直接将其添加到 MCP 客户端配置中（例如 claude_desktop_config.json 或 .claude/settings.json）：

{
  "mcpServers": {
    "nextcloud": {
      "command": "uvx",
      "args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

提示

请在 Nextcloud 的 设置 > 安全 > 设备和会话 中生成应用密码，而不要使用登录密码。

Docker

如需使用语义搜索等完整功能，请使用 Docker 运行：

docker run -p 127.0.0.1:8000:8000 --rm \
  -e NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
  -e NEXTCLOUD_USERNAME=your_username \
  -e NEXTCLOUD_PASSWORD=your_app_password \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

然后将 MCP 客户端（Claude Desktop、IDE、mcp dev 等）连接到 http://127.0.0.1:8000/mcp。

有关 Kubernetes 的说明，请参阅 cbcoutinho/helm-charts。有关其他部署选项和 Compose 配置文件，请参阅 docs/installation.md。

主要功能

• 110 多个 MCP 工具 - 全面覆盖 10 个 Nextcloud 应用的 API
• MCP 资源 - 用于浏览 Nextcloud 数据的结构化数据 URI
• 语义搜索（实验性） - 可选的向量搜索，支持笔记、文件、新闻条目、Deck 卡片和邮件（需要 Qdrant + Ollama）
• 文档处理 - 从 PDF、DOCX 和图像中进行 OCR 和文本提取，并提供进度通知
• 灵活部署 - 支持 Docker、Kubernetes（Helm chart）、VM 或本地安装
• 适用于生产环境的身份验证 - 使用应用密码的基本身份验证；通过 Login Flow v2 支持多用户——MCP 客户端通过 OAuth 进行身份验证，服务会透明地处理 Nextcloud 应用密码
• 基于标签的文件排除 - 为敏感文件/文件夹添加配置好的 Nextcloud 系统标签（EXCLUDED_TAGS），即可将其从 MCP 文件工具中隐藏。请参阅 docs/configuration.md
• 多种传输方式 - streamable-http（默认）和 stdio

支持的应用

应用	工具	功能
Notes	7	完整的增删改查（CRUD）、关键词搜索、语义搜索
Calendar	20+	事件、待办事项（任务）、重复事件、参与者、可用时间
Contacts	8	完整的 CardDAV 支持、通讯录
Files (WebDAV)	14	文件系统访问、OCR/文档处理、文件评论
Deck	15	看板、列表、卡片、标签、任务分配
Cookbook	13	食谱管理、URL 导入（schema.org）
Tables	5	对 Nextcloud Tables 执行行操作
Sharing	10+	创建和管理共享
News	8	订阅源、文件夹、条目、订阅源运行状况监控
Mail	13	账户、邮箱、邮件、附件、发送；标记（已读/未读、星标）、标签、移动、删除
Collectives	16	对集体、页面和标签执行完整的增删改查（CRUD）
Talk (spreed)	6	列出对话、读取/发送消息、标记为已读、列出参与者
Shopping List	12	清单和条目 — 一次调用即可添加整份食谱的食材、勾选条目、清除已勾选项
Semantic Search	2+	对 Notes、Files、News 条目、Deck 卡片和 Mail 邮件进行向量搜索（实验性功能，需主动启用并配置基础设施）

想了解是否支持其他 Nextcloud 应用？提交议题或贡献拉取请求！

身份验证

MCP 服务使用应用专用密码（Basic Auth）向 Nextcloud 进行身份验证。支持三种部署模式：

模式	适用场景
单用户（BasicAuth）	个人使用、开发、单用户部署
多用户（BasicAuth 透传）	客户端通过 Authorization 标头发送凭据的多用户设置
多用户（Login Flow v2）	多用户/托管部署 — 客户端通过 OAuth 向 MCP 服务进行身份验证，服务从 Nextcloud 获取每位用户的应用密码并透明地使用

不再支持直接使用 OAuth 连接 Nextcloud（这需要对 user_oidc 进行上游补丁，但这些补丁从未合并）。Login Flow v2 取代了它，适用于多用户部署，并且可与原版 Nextcloud 配合使用。

设置说明请参阅 docs/authentication.md。

Nextcloud 内的 AI

此服务面向运行在 Nextcloud 之外的 AI 助手 — Claude Code、IDE、桌面客户端。但 Nextcloud 有自己的聊天功能，即 Assistant 应用，有两种方式可以让它访问你的内容。

为 Assistant 的“与 AI 聊天”提供回答	所需条件	功能
Context Agent（由 Nextcloud 提供）	AppAPI 和一个用于运行 ExApp 的独立容器	在你的 Nextcloud 上执行操作 — 发送 Talk 消息、创建事件及执行其他写入操作，并需经过确认步骤
Astrolabe + 此服务	Astrolabe 应用，以及可从该应用访问的此服务	根据你自己的文档回答并引用来源：每条陈述都链接到其来源文件、笔记或卡片。只读

Astrolabe 是一个 Nextcloud 应用，会将自身注册为 Assistant 的 Agent 提供方，因此无需 AppAPI，也无需额外容器 — Assistant 会与它通信，并通过此服务搜索你的内容。每位用户的问题都以其自身身份运行，因此不会有人看到他们原本无法打开的内容。

你可以同时安装这两者，并根据实例选择使用哪一个；也可以都不安装：使用外部 MCP 客户端连接此服务不需要这些组件。

设置说明请参阅 Astrolabe setup guide。有关对比背后的架构详情，请参阅 docs/comparison-context-agent.md。

语义搜索

一个实验性的 RAG 流水线，让 MCP 客户端可以按含义而非关键词查找 Nextcloud 内容——搜索“汽车”也会找到关于“车辆”或“交通”的笔记。默认禁用（ENABLE_SEMANTIC_SEARCH=false）；需要安装 semantic 扩展（pip install 'nextcloud-mcp-server[semantic]'，已包含在 Docker 镜像中）、向量数据库和嵌入服务。请参阅 docs/semantic-search-architecture.md 和 docs/configuration.md。

如果要调整结果的排序——使用交叉编码器将融合排名分数转换为校准后的相关性分数，可通过 Infinity/vLLM 自托管或使用 Cohere 托管，且可选择是否使用嵌入网关——请参阅 docs/reranking.md。

提示

不想运行 Qdrant 和嵌入服务？ Astrolabe Cloud（正在开发中）提供语义搜索和后台同步托管服务。

文档

• 安装 — Docker、Compose 配置文件、本地环境、VM
• 配置 — 环境变量、文档处理、语义搜索设置
• 身份验证 — Basic Auth、Login Flow v2
• 运行服务 — 启动、管理、故障排查
• 应用文档 — 各应用指南（Notes、Calendar、Contacts、WebDAV、Deck、Cookbook、Tables）
• 语义搜索架构 + 向量同步 UI
• 重排序 — 交叉编码器相关性评分（Infinity、vLLM、Cohere）；无需嵌入网关
• Login Flow v2 — 推荐的多用户设置（架构、环境变量、权限范围参考、故障排查）
• 故障排查 · 与 Context Agent 的比较

参与贡献

欢迎贡献！

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

安全

发现安全问题？请勿公开提交 GitHub issue。 请使用 GitHub 的私密漏洞报告，如果无法使用 GitHub，请发送电子邮件至 [email protected]。详情请参阅 SECURITY.md。

许可证

本项目采用 AGPL-3.0 许可证。详情请参阅 LICENSE。

Star 历史

参考资料

• Model Context Protocol
• MCP Python SDK
• Nextcloud