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. 提交拉取請求