MCP Nextcloud

🚀 Nextcloud MCP Server

Nextcloud MCP Server 允许 OpenAI 的 GPT、Google 的 Gemini 或 Anthropic 的 Claude 等大语言模型（LLMs）与你的 Nextcloud 实例进行交互。这使得用户能够自动化执行 Nextcloud 中的各种操作，涵盖笔记、日历、联系人、表格以及 WebDAV 文件操作等多个方面。

🚀 快速开始

前提条件

• Node.js 18+
• 能够访问 Nextcloud 实例
• 安装 npm 或 yarn 包管理器

快速安装（推荐）

使用 npm 直接安装并作为 MCP 服务器运行：

# 全局安装
npm install -g mcp-nextcloud

# 或者在项目中本地安装
npm install mcp-nextcloud

作为 MCP 服务器使用

安装完成后，你可以直接运行 MCP 服务器：

# 全局安装时
mcp-nextcloud

# 本地安装时
npx mcp-nextcloud

# 或者使用 npm 脚本
npm exec mcp-nextcloud

环境设置

创建一个 .env 文件，并填写你的 Nextcloud 凭证：

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

与大语言模型应用集成

将其添加到你的 MCP 客户端配置中（例如 Claude Desktop、Continue 等）：

{
  "mcpServers": {
    "nextcloud": {
      "command": "mcp-nextcloud",
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

✨ 主要特性

• 语言重写：本项目使用 TypeScript 完全重写了原基于 Python 的 cbcoutinho/nextcloud-mcp-server。
• Smithery 支持：新增了对 Smithery 部署的全面支持，可实现一键云部署，同时支持通过 Smithery 操场进行本地测试。
• 项目结构优化：项目结构已适配 Node.js/TypeScript 环境，并集成了 MCP SDK。
• 依赖管理：使用 npm 进行包管理。
• 部署方式灵活：支持本地开发和通过 Smithery 进行云部署。

📦 安装指南

本地开发设置

1. 克隆仓库：

git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
cd mcp-nextcloud

2. 安装依赖：

npm install

3. 配置 Nextcloud 凭证（见配置部分）

4. 构建项目：

npm run build

配置

环境变量

在根目录下根据 .env.sample 创建一个 .env 文件：

# .env
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password_or_login_password

⚠️ 重要提示

请使用专用的 Nextcloud 应用密码，而不是常规登录密码。你可以在 Nextcloud 安全设置中生成应用密码。

Smithery 配置

通过 Smithery 部署时，你可以通过以下方式配置凭证：

• 环境变量（如上所述）
• Smithery 配置界面（推荐用于云部署）

部署与使用

选项 1：npm 包（推荐给最终用户）

用户最便捷的启动方式：

npm install -g mcp-nextcloud
mcp-nextcloud

这将安装一个全局 CLI，可直接与 MCP 客户端配合使用。

选项 2：使用 Smithery 操场进行本地开发

开发期间在本地测试服务器的最快方式：

npm run dev

这将：

1. 构建 TypeScript 项目
2. 启动 Smithery 开发服务器
3. 自动在浏览器中打开 Smithery 操场
4. 连接到本地服务器进行即时测试

选项 3：通过 Smithery 进行云部署

1. 确保项目已配置：

npm run build

2. 部署到 Smithery：

npm run deploy

3. 按照 Smithery 部署提示安全配置你的 Nextcloud 凭证。

手动本地开发

对于传统的本地开发：

npm run start

服务器将启动并监听 MCP 连接。

发布到 npm

维护者操作

要将此包发布到 npm：

1. 准备发布：

npm run build
npm version patch|minor|major

2. 发布到 npm：

npm publish

3. 验证发布：

npm view mcp-nextcloud

发布检查清单

• [ ] 所有测试通过（确认 Smithery 部署正常工作）
• [ ] TypeScript 构建无错误 (npm run build)
• [ ] 版本号适当更新 (npm version)
• [ ] README 已更新更改内容
• [ ] .npmignore 正确排除开发文件
• [ ] CLI 可执行文件正常工作 (dist/cli.js)

双重部署策略

本项目同时支持两种部署方式：

• Smithery：用于云部署和开发测试
• npm：用于最终用户安装和 MCP 客户端集成

Smithery 配置 (smithery.yaml) 和 npm 包配置可以共存且互不干扰。

💻 使用示例

基础用法

// 基本搜索 - 查找包含 "FAQ Dean List" 的所有文件
await nextcloud_webdav_search_files({
  query: "FAQ Dean List"
});

高级用法

// 高级搜索 - 查找 2024 年的 PDF 报告
await nextcloud_webdav_search_files({
  query: "report 2024",
  fileTypes: ["pdf"],
  searchIn: ["filename", "content"],
  limit: 20,
  includeContent: true,
  quickSearch: true
});

// 指定目录并设置日期范围的搜索
await nextcloud_webdav_search_files({
  query: "meeting notes",
  basePath: "/Documents",
  searchIn: ["filename", "content"],
  dateRange: {
    from: "2024-01-01",
    to: "2024-12-31"
  }
});

// 根据文件特征搜索
await nextcloud_webdav_search_files({
  query: "configuration files",
  sizeRange: { min: 1024, max: 102400 }, // 1KB - 100KB
  fileTypes: ["json", "yaml", "xml", "conf"]
});

// 对大目录进行快速搜索（优化）
await nextcloud_webdav_search_files({
  query: "budget",
  basePath: "/", // 根目录
  quickSearch: true, // 启用优化
  limit: 25,
  maxDepth: 2 // 限制搜索深度
});

📚 详细文档

支持的 Nextcloud 应用

可用工具（共 30 个）

📝 笔记工具（5 个工具）

📅 日历工具（6 个工具）

👥 联系人工具（6 个工具）

📊 表格工具（6 个工具）

📁 WebDAV 文件系统工具（6 个工具）

🔍 革命性的统一 WebDAV 搜索功能

这个 MCP 服务器的亮点是强大的 WebDAV 文件统一搜索系统，它受到了我创建的另一个 MCP mcp-datagovmy 的现代搜索界面的启发。这彻底改变了你与 Nextcloud 文件的交互方式，无需再指定确切的文件路径。

✨ 关键特性

• 🎯 多范围搜索：同时在文件名、文件内容和元数据中进行搜索
• 🧠 智能文件类型检测：自动处理文本文件、代码、配置文件、文档和媒体
• 🔧 高级过滤：按文件类型、大小范围、修改日期和目录进行过滤
• 📈 智能排序：结果按相关性排序，对近期文件和精确匹配给予额外加分
• 👀 内容预览：可选的匹配文本文件内容预览
• ⚡ 性能优化：智能缓存、超时保护和并行处理
• 🛡️ 错误恢复：备用策略可防止超时并提供有用的建议

📋 完整参数参考

🎯 性能提示

• 对于根目录搜索：使用 quickSearch: true 和 maxDepth: 2 - 3 以获得更快的结果
• 对于特定目录：使用 basePath: "/Documents" 而不是搜索根目录 "/"
• 对于大结果集：添加 fileTypes 过滤器以缩小搜索范围
• 对于超时问题：启用 quickSearch 并使用较小的 limit 值

🧪 测试工具（1 个工具）

🔄 搜索革命前后对比

统一搜索前

// 你必须知道确切的路径
await nextcloud_webdav_read_file({
  path: "/Documents/Finance/Reports/Q4_Budget_Analysis_2024.pdf"
});

// 需要多次调用以探索
await nextcloud_webdav_list_directory({ path: "/" });
await nextcloud_webdav_list_directory({ path: "/Documents" });
await nextcloud_webdav_list_directory({ path: "/Documents/Finance" });
// ... 依此类推

统一搜索后 ✨

// 在整个 Nextcloud 中进行自然语言搜索！
await nextcloud_webdav_search_files({
  query: "Q4 budget analysis 2024",
  fileTypes: ["pdf"]
});

// 无论文件位于何处，都能立即找到！

🛠️ 高级搜索策略

内容感知搜索

系统智能地提取并搜索以下内容：

• 📝 文本文件：.txt, .md, .csv - 全内容索引
• 💻 代码文件：.js, .ts, .py, .html, .css - 语法感知搜索
• ⚙️ 配置文件：.json, .xml, .yaml - 结构感知索引
• 📄 文档：.pdf, .docx - 元数据和属性
• 🎬 媒体文件：图像、视频 - EXIF 数据和元数据

智能排序系统

结果使用高级算法进行排序：

1. 精确文件名匹配 → 100 分
2. 文件名中的单词边界匹配 → 80 分
3. 部分文件名匹配 → 60+ 分（位置加分）
4. 内容频率匹配 → 50+ 分（词密度）
5. 近期文件加分 → +10 分（最近 30 天）
6. 文件类型偏好 → +5 分（文本/代码文件）
7. 大小便利性 → +5 分（小于 100KB 的文件）

错误处理与恢复

• 🕐 20 秒超时保护 - 防止操作挂起
• 🔄 自动备用搜索 - 如果索引失败，回退到目录列表
• 💡 智能建议 - 提供优化的有用提示
• 📊 性能指标 - 显示搜索持续时间和结果数量

🔧 技术细节

项目结构

├── src/
│   ├── index.ts          # 主要 Smithery 入口点
│   ├── app.ts            # 旧版入口点
│   ├── client/           # Nextcloud API 客户端
│   ├── models/           # TypeScript 接口
│   └── server/           # 工具实现
├── smithery.yaml         # Smithery 配置
├── package.json          # 项目依赖和脚本
└── README.md            # 本文件

Smithery 集成

本项目全面支持 Smithery，具备以下特性：

• smithery.yaml：指定 TypeScript 运行时
• 开发服务器：支持热重载的本地测试
• 一键部署：通过单个命令部署到云端
• 配置管理：安全的凭证处理
• 操场集成：即时测试界面

📄 许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL - 3.0) 许可协议 - 详情请参阅 LICENSE 文件。

致谢

• 原 Python 实现由 cbcoutinho 完成
• 基于 Model Context Protocol 构建
• 可通过 Smithery 进行部署

故障排除

常见问题

1. WebDAV/日历/联系人出现 404 错误：

   • 确保你的 Nextcloud 凭证正确
   • 验证 Nextcloud 应用（日历、联系人）已安装并启用
   • 检查你的应用密码是否具有必要的权限

2. 身份验证失败：

   • 使用应用密码而不是常规密码
   • 验证 NEXTCLOUD_HOST URL 是否正确（包括 https://）
   • 确保可以访问 Nextcloud 实例

3. 工具缺失：

   • 运行 hello 工具以验证所有 30 个工具是否可用
   • 检查服务器日志中是否有任何初始化错误

4. 搜索超时问题：

   • 对于根目录搜索，使用 quickSearch: true
   • 指定 basePath 如 "/Documents" 而不是搜索根目录 "/"
   • 添加 fileTypes 过滤器以缩小搜索范围
   • 减小 maxDepth 参数以获得更快的结果

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 使用 npm run dev 进行测试
5. 提交拉取请求