金大哥 - mcp-nextcloud MCP 详情

article

README

🚀 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 进行云部署。

📦 安装指南

本地开发设置

克隆仓库：

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

安装依赖：

npm install

配置 Nextcloud 凭证（见配置部分）
构建项目：

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

这将：

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

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

确保项目已配置：

npm run build

部署到 Smithery：

npm run deploy

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

手动本地开发

对于传统的本地开发：

npm run start

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

发布到 npm

维护者操作

要将此包发布到 npm：

准备发布：

npm run build
npm version patch|minor|major

发布到 npm：

npm publish

验证发布：

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 应用

| 应用 | 支持状态 | 描述 | |-----|----------------|-------------| | 笔记 | ✅ 完全支持 | 创建、读取、更新、删除、搜索和追加笔记。 | | 日历 | ✅ 完全支持 | 完整的日历集成 - 通过 CalDAV 管理日历和事件。 | | 表格 | ✅ 完全支持 | 完整的表格操作 - 列出表格、获取架构并对行执行 CRUD 操作。 | | 文件 (WebDAV) | ✅ 完全支持 | 完整的文件系统访问 - 浏览目录、读写文件、创建/删除资源。 | | 联系人 | ✅ 完全支持 | 通过 CardDAV 创建、读取、更新和删除联系人及地址簿。 |

可用工具（共 30 个）

📝 笔记工具（5 个工具）

| 工具 | 描述 | |------|-------------| | nextcloud_notes_create_note | 使用标题、内容和类别创建新笔记 | | nextcloud_notes_update_note | 通过 ID 更新现有笔记，可选择更新标题、内容或类别 | | nextcloud_notes_append_content | 向现有笔记追加内容，并使用清晰的分隔符 | | nextcloud_notes_search_notes | 通过标题或内容搜索笔记，并进行结果过滤 | | nextcloud_notes_delete_note | 通过 ID 删除笔记 |

📅 日历工具（6 个工具）

| 工具 | 描述 | |------|-------------| | nextcloud_calendar_list_calendars | 列出用户可用的所有日历 | | nextcloud_calendar_create_event | 使用摘要、描述、日期和位置创建日历事件 | | nextcloud_calendar_list_events | 列出日历中的事件，可选择进行日期过滤 | | nextcloud_calendar_get_event | 获取特定事件的详细信息 | | nextcloud_calendar_update_event | 更新现有事件的任何方面 | | nextcloud_calendar_delete_event | 删除日历事件 |

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

| 工具 | 描述 | |------|-------------| | nextcloud_contacts_list_addressbooks | 列出用户可用的所有地址簿 | | nextcloud_contacts_create_addressbook | 使用显示名称和描述创建新地址簿 | | nextcloud_contacts_delete_addressbook | 通过 ID 删除地址簿 | | nextcloud_contacts_list_contacts | 列出特定地址簿中的所有联系人 | | nextcloud_contacts_create_contact | 使用全名、电子邮件、电话、地址和组织创建新联系人 | | nextcloud_contacts_delete_contact | 从地址簿中删除联系人 |

📊 表格工具（6 个工具）

| 工具 | 描述 | |------|-------------| | nextcloud_tables_list_tables | 列出用户可用的所有表格 | | nextcloud_tables_get_schema | 获取特定表格的架构/结构，包括列信息 | | nextcloud_tables_read_table | 读取表格中的所有行 | | nextcloud_tables_insert_row | 使用键值数据向表格中插入新行 | | nextcloud_tables_update_row | 更新表格中的现有行 | | nextcloud_tables_delete_row | 从表格中删除行 |

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

| 工具 | 描述 | |------|-------------| | nextcloud_webdav_search_files | 🔍 新增！ 跨文件名、内容和元数据的统一搜索 - 无需指定确切路径 | | nextcloud_webdav_list_directory | 列出 Nextcloud 任何路径下的文件和目录 | | nextcloud_webdav_read_file | 从 Nextcloud 读取文件内容 | | nextcloud_webdav_write_file | 在 Nextcloud 中创建或更新文件内容 | | nextcloud_webdav_create_directory | 在 Nextcloud 中创建新目录 | | nextcloud_webdav_delete_resource | 从 Nextcloud 中删除文件或目录 |

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

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

✨ 关键特性

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

📋 完整参数参考

| 参数 | 类型 | 默认值 | 描述 | 示例 | |-----------|------|---------|-------------|---------| | query | 字符串 | 必需 | 搜索词 - 支持多个单词 | "FAQ Dean List" | | searchIn | 数组 | ["filename", "content"] | 搜索范围: filename, content, metadata | ["filename", "content", "metadata"] | | fileTypes | 数组 | 所有类型 | 要包含的文件扩展名 | ["pdf", "txt", "md", "docx"] | | basePath | 字符串 | "/" | 要搜索的目录 | "/Documents/Reports" | | limit | 数字 | 50 | 要返回的最大结果数 | 20 | | includeContent | 布尔值 | false | 是否包含文本文件的内容预览 | true | | caseSensitive | 布尔值 | false | 是否区分大小写匹配 | true | | quickSearch | 布尔值 | true | 是否使用优化模式进行根目录搜索 | false | | maxDepth | 数字 | 3 | 最大目录深度 (1 - 10) | 5 | | sizeRange | 对象 | 无限制 | 文件大小过滤器（以字节为单位） | {min: 1024, max: 1048576} | | dateRange | 对象 | 所有日期 | 最后修改日期过滤器 | {from: "2024-01-01", to: "2024-12-31"} |

🎯 性能提示

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

🧪 测试工具（1 个工具）

| 工具 | 描述 | |------|-------------| | hello | 验证服务器连接并列出所有可用工具 |

🔄 搜索革命前后对比

统一搜索前

// 你必须知道确切的路径
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 数据和元数据

智能排序系统

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

精确文件名匹配 → 100 分
文件名中的单词边界匹配 → 80 分
部分文件名匹配 → 60+ 分（位置加分）
内容频率匹配 → 50+ 分（词密度）
近期文件加分 → +10 分（最近 30 天）
文件类型偏好 → +5 分（文本/代码文件）
大小便利性 → +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 进行部署

故障排除

常见问题

WebDAV/日历/联系人出现 404 错误：
- 确保你的 Nextcloud 凭证正确
- 验证 Nextcloud 应用（日历、联系人）已安装并启用
- 检查你的应用密码是否具有必要的权限
身份验证失败：
- 使用应用密码而不是常规密码
- 验证 NEXTCLOUD_HOST URL 是否正确（包括 https://）
- 确保可以访问 Nextcloud 实例
工具缺失：
- 运行 hello 工具以验证所有 30 个工具是否可用
- 检查服务器日志中是否有任何初始化错误
搜索超时问题：
- 对于根目录搜索，使用 quickSearch: true
- 指定 basePath 如 "/Documents" 而不是搜索根目录 "/"
- 添加 fileTypes 过滤器以缩小搜索范围
- 减小 maxDepth 参数以获得更快的结果

贡献

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