MCP Nextcloud

🚀 Nextcloud MCP Server

Nextcloud MCP（Model Context Protocol）サーバーは、OpenAIのGPT、GoogleのGemini、またはAnthropicのClaudeなどの大規模言語モデル（LLM）がNextcloudインスタンスとやり取りできるようにします。これにより、ノート、カレンダー、連絡先、テーブル、WebDAVファイル操作など、さまざまなNextcloudアクションを自動化できます。

🚀 クイックスタート

このサーバーをすぐに使い始めるには、以下の手順に従ってください。

npmを使ったクイックスタート（推奨）

npmから直接インストールし、MCPサーバーとして実行します。

# グローバルにインストール
npm install -g mcp-nextcloud

# または、プロジェクト内にローカルインストール
npm install mcp-nextcloud

MCPサーバーとしての使用

インストール後、MCPサーバーを直接実行できます。

# グローバルにインストールした場合
mcp-nextcloud

# ローカルにインストールした場合
npx mcp-nextcloud

# または、npmスクリプトを使用
npm exec mcp-nextcloud

環境設定

Nextcloudの資格情報を含む.envファイルを作成します。

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パッケージマネージャー

ローカル開発環境のセットアップ

1. リポジトリをクローンします。

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

2. 依存関係をインストールします。

npm install

3. Nextcloudの資格情報を設定します（設定セクションを参照）。
4. プロジェクトをビルドします。

npm run build

✨ 主な機能

このサーバーは、複数のNextcloudアプリと統合されており、LLMがNextcloudデータとやり取りできるように、5つの主要カテゴリにわたる合計30のツールを提供します。

サポートされるNextcloudアプリ

利用可能なツール（合計30）

📝 ノートツール（5つのツール）

📅 カレンダーツール（6つのツール）

👥 連絡先ツール（6つのツール）

📊 テーブルツール（6つのツール）

📁 WebDAVファイルシステムツール（6つのツール）

🔍 革新的な統一WebDAV検索機能

このMCPサーバーの最大の特長は、WebDAVファイルの強力な統一検索システムです。これは、私が作成した別の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: "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 // 検索深度を制限
});

📋 完全なパラメータリファレンス

🎯 パフォーマンスのヒント

• ルートディレクトリの検索：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秒のタイムアウト保護 - 操作のハングを防止
• 🔄 自動フォールバック検索 - インデックス作成が失敗した場合、ディレクトリ一覧にフォールバック
• 💡 インテリジェント提案 - 最適化のための有益な提案を提供
• 📊 パフォーマンスメトリクス - 検索時間と結果数を表示

📦 インストール

npmパッケージ（エンドユーザー向けに推奨）

ユーザーが始める最も簡単な方法は、以下のコマンドを実行することです。

npm install -g mcp-nextcloud
mcp-nextcloud

これにより、グローバルCLIがインストールされ、MCPクライアントで直接使用できます。

Smitheryプレイグラウンドを使ったローカル開発

開発中にサーバーをローカルでテストする最速の方法は、以下のコマンドを実行することです。

npm run dev

これにより、以下のことが行われます。

1. TypeScriptプロジェクトがビルドされます。
2. Smithery開発サーバーが起動します。
3. ブラウザでSmitheryプレイグラウンドが自動的に開きます。
4. ローカルサーバーに接続してすぐにテストできます。

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)

デュアルデプロイ戦略

このプロジェクトは、2つのデプロイ方法を同時にサポートしています。

• Smithery：クラウドデプロイと開発テスト用
• npm：エンドユーザーのインストールとMCPクライアントの統合用 Smitheryの構成 (smithery.yaml) とnpmパッケージの構成は、相互に干渉することなく共存します。

Smithery統合

このプロジェクトは、以下の機能を備えた完全なSmitheryサポートを含んでいます。

• smithery.yaml：TypeScriptランタイムを指定
• 開発サーバー：ホットリロードでのローカルテスト
• ワンクリックデプロイ：1つのコマンドでクラウドにデプロイ
• 構成管理：安全な資格情報管理
• プレイグラウンド統合：即時テストインターフェイス

🔧 技術詳細

プロジェクト構造

├── src/
│   ├── index.ts          # メインのSmitheryエントリポイント
│   ├── app.ts            # レガシーエントリポイント
│   ├── client/           # Nextcloud APIクライアント
│   ├── models/           # TypeScriptインターフェース
│   └── server/           # ツールの実装
├── smithery.yaml         # Smithery構成
├── package.json          # プロジェクトの依存関係とスクリプト
└── README.md            # このファイル

貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. npm run dev でテストします。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトは、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 パラメータを減らして、より速い結果を得てください。