Nextcloud MCP 服务器

Nextcloud MCP服务器

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

使用Claude、GPT、Gemini和其他MCP兼容客户端创建笔记、管理日历、处理联系人以及通过自然语言工作流浏览文件。

快速入门（NixOS优先）

此存储库现在包括：

• flake.nix 用于开发shell和可运行的应用程序
• nixosModules.default 用于在NixOS上部署服务
• tools/nextcloud-mcp-server.service 作为通用systemd模板

1） 将此存储库添加为系统flake中的输入

{
  inputs.nextcloud-mcp-server.url = "github:YOUR_ORG/nextcloud-mcp-server";
}

2） 在NixOS配置中启用该模块

{
  imports = [ inputs.nextcloud-mcp-server.nixosModules.default ];

  services.nextcloud-mcp-server = {
    enable = true;
    workingDirectory = "/srv/nextcloud-mcp-server";
    environmentFile = "/etc/nextcloud-mcp-server.env";
    host = "127.0.0.1";
    port = 8000;
    transport = "streamable-http";
    metricsPort = 9090;
  };
}

3） 使用Nextcloud凭据创建环境文件

sudo install -m 0600 -o root -g root /dev/null /etc/nextcloud-mcp-server.env
sudo tee /etc/nextcloud-mcp-server.env >/dev/null <<'EOF'
NEXTCLOUD_HOST=https://cloud.example.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password
EOF

4） 部署和验证

sudo nixos-rebuild switch
systemctl --no-pager --full status nextcloud-mcp-server
curl -fsS http://127.0.0.1:8000/health/ready

5） 连接您的MCP客户端

• http://127.0.0.1:8000/mcp 为了 streamable-http
• http://127.0.0.1:8000/sse 用于SSE传输（如果已配置）

如何传递凭证

服务器从环境变量中读取凭据：

• NEXTCLOUD_HOST
• NEXTCLOUD_USERNAME
• NEXTCLOUD_PASSWORD

在NixOS上，推荐的方法是 services.nextcloud-mcp-server.environmentFile.

安全指南：

• 使用Nextcloud的应用程序密码，而不是您的交互式帐户密码。
• 将env文件保存在git之外（例如， /etc/nextcloud-mcp-server.env).
• 将文件权限限制为 0600.
• 如果应用程序密码被暴露，请对其进行轮换。
• 不要在中硬编码凭据 configuration.nix、脚本、提交历史记录或屏幕截图。

可选环境变量：

• TOKEN_ENCRYPTION_KEY （建议用于加密令牌持久性功能）
• TOKEN_STORAGE_DB （默认值为 /tmp/tokens.db，覆盖持久存储）
• METRICS_PORT （默认值 9090)

LLM代理：NixOS安装运行手册

当要求代理LLM会话在NixOS主机上安装和配置此MCP服务器时，请使用此部分。

代理应首先请求的输入

• Nextcloud URL
• Nextcloud用户名
• Nextcloud应用程序密码
• 所需的MCP绑定主机和端口
• 是否需要反向代理/TLS

代理工作流程检查表

1. 确认主机是基于NixOS和薄片的。
2. 将此仓库添加为flake输入。
3. 导入 nixosModules.default.
4. 配置 services.nextcloud-mcp-server.
5. 创建 /etc/nextcloud-mcp-server.env 随着 0600 权限。
6. 应用配置 nixos-rebuild switch.
7. 验证服务运行状况终结点。
8. 运行MCP烟雾测试（列出目录，读取文件）。

代理会话的命令序列

sudo install -d -m 0755 /srv/nextcloud-mcp-server
sudo install -m 0600 -o root -g root /dev/null /etc/nextcloud-mcp-server.env
sudoedit /etc/nextcloud-mcp-server.env
sudo nixos-rebuild switch
systemctl --no-pager --full status nextcloud-mcp-server
curl -fsS http://127.0.0.1:8000/health/ready

代理完成标准

成功运行代理程序应返回：

• 服务状态(active (running))
• 健康检查有效载荷来自 /health/ready
• MCP端点URL
• 任何所需的后续操作（反向代理、防火墙、OAuth模式、备份）

替代快速入门

Docker（自托管）

cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

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

curl http://127.0.0.1:8000/health/ready

Smithery（管理）

使用 史密瑟里 用于托管设置。

[！注意] 默认情况下，Smithery在无状态模式下运行，没有完整的语义搜索基础设施。

主要特点

• 主要Nextcloud应用程序中的90多种MCP工具
• 用于基于URI的结构化数据访问的MCP资源
• 具有可选矢量基础结构的语义搜索（实验性）
• 文档处理（支持文件的OCR/文本提取）
• 灵活部署：NixOS、Docker、Kubernetes、VM、本地
• 身份验证模式：基本身份验证（推荐）、OAuth/OIDC（实验）
• 多次运输： streamable-httpHTTP、SSE

支持的应用程序

认证

建议在生产单用户设置中使用带有应用程序密码的基本身份验证。

[！重要] OAuth2/OIDC支持尚处于试验阶段，取决于上游 user_oidc 行为。 看 docs/oauth-upstream-status.md 和 docs/authentication.md.

语义搜索

语义搜索是实验性的，可以选择加入：

• 默认情况下已禁用(ENABLE_SEMANTIC_SEARCH=false)
• 需要额外的基础设施（例如Qdrant和嵌入提供程序）
• 支持支持的应用程序的语义检索工作流

看 docs/语义搜索架构.md 和 docs/configuration.md.

文档

入门指南

• 安装 -Docker、Kubernetes、本地、VM
• NixOS和systemd -缺陷/模块使用和服务模板
• 配置 -环境变量和高级选项
• 认证 -基本身份验证与OAuth2/OIDC设置
• 运行服务器 -启动、管理、故障排除

特性

• 应用程序文档 -笔记、日历、联系人、WebDAV、甲板、食谱、表格
• 文档处理 -OCR/文本提取设置
• 语义搜索架构 -矢量搜索架构
• 矢量同步UI指南 -用于语义同步和测试的浏览器UI

高级主题

• OAuth架构 -OAuth设计和流程
• OAuth快速入门 -快速OAuth引导
• OAuth设置指南 -完整的OAuth配置
• 故障排除 -常见问题和修复
• 与上下文代理的比较 -用例比较

贡献

• 报告错误或请求功能： GitHub 问题
• 提交改进： 拉取请求
• 开发工作流程说明： 代理商.md

安全

• 使用应用程序密码进行基本身份验证部署。
• 将凭据文件保存在git之外。
• 首选最小权限和作用域凭据。
• 私下向维护人员报告安全问题。

许可证

AGPL-3.0。看 许可证.

参考文献

• 模型上下文协议
• MCP Python SDK
• 云端下一站