麦格 nex云

Name: 麦格 nex云
Author: hithereiamaliff

作者：hithereiamaliff9 星标更新：2025-09-19

安装使用来源：spider==github.com

项目介绍

Nextcloud MCP 服务器

注意： 本项目是对原基于Python的 cbcoutinho/nextcloud-mcp-server 的完全重写，现在使用的是 TypeScript，并且支持通过 Smithery 进行一键云部署。

与原始仓库的主要区别：

语言： 本项目使用 TypeScript 编写，而原始项目使用 Python。

Smithery 支持： 增加了对 Smithery 部署和本地测试的支持。

项目结构： 项目结构已调整以适应 Node.js/TypeScript 环境，并集成了 MCP SDK。

依赖管理： 本项目使用 npm 进行包管理，而原始项目使用 Python 的依赖管理工具。

部署： 现在支持本地开发和通过 Smithery 进行云部署。

Nextcloud MCP（模型上下文协议）服务器允许像 OpenAI 的 GPT、Google 的 Gemini 或 Anthropic 的 Claude 这样的大型语言模型（LLMs）与你的 Nextcloud 实例进行交互。这使得可以自动化各种 Nextcloud 功能，包括笔记、日历、联系人、表格和 WebDAV 文件操作。

特性

该服务器提供了与多个 Nextcloud 应用程序的集成，使 LLM 可以通过一组全面的 30 种工具 在 5 个主要类别中与你的 Nextcloud 数据进行交互。

支持的 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`	创建具有摘要、描述、日期和地点的日历事件
`next-Cloud_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 服务器的亮点是强大的 统一搜索系统，灵感来自现代搜索界面，如我创建的另一个 MCP：mcp-datagovmy。这彻底改变了你与 Nextcloud 文件的互动方式，消除了指定确切文件路径的需求。

✨ 主要特点

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

🚀 使用示例

// 基础搜索 - 查找所有包含“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: "会议记录",
  basePath: "/Documents",
  searchIn: ["filename", "content"],
  dateRange: {
    from: "2024-01-01",
    to: "2024-12-31"
  }
});

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

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

📋 完整参数参考

参数	类型	默认值	描述	示例
`query`	string	必填	搜索词 - 支持多个单词	`"FAQ Dean List"`
`searchIn`	array	`["filename", "content"]`	搜索范围：`filename`、`content`、`metadata`	`["filename", "content", "metadata"]`
`fileTypes`	array	所有类型	要包含的文件扩展名	`["pdf", "txt", "md", "docx"]`
`basePath`	string	`"/"`	要搜索的目录	`"/Documents/Reports"`
`limit`	number	`50`	返回的最大结果数	`20`
`includeContent`	boolean	`false`	包含文本文件的内容预览	`true`
`caseSensitive`	boolean	`false`	区分大小写的匹配	`true`
`quickSearch`	boolean	`true`	对根目录搜索启用优化模式	`false`
`maxDepth`	number	`3`	最大目录深度（1-10）	`5`
`sizeRange`	object	无限制	文件大小过滤器（字节）	`{min: 1024, max: 1048576}`
`dateRange`	object	所有日期	最后修改日期过滤器	`{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 预算分析 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 秒超时保护 - 防止挂起的操作
🔄 自动回退搜索 - 如果索引失败，则回退到目录列表
💡 智能建议 - 提供有助于优化的有用提示
📊 性能指标 - 显示搜索持续时间和结果计数

安装

使用 npm 快速开始（推荐）

直接从 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

与 LLM 应用程序集成

添加到你的 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"
      }
    }
  }
}

先决条件

Node.js 18+
访问 Nextcloud 实例
npm 或 yarn 包管理器

本地开发设置

克隆仓库：

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 Playground

开发期间最快的本地测试方法：

npm run dev

这将：

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

方案 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 配