Nextcloud MCP Server

Nextcloud MCP サーバー

AI アシスタントをお使いの Nextcloud インスタンスに接続する、本番環境対応の MCP サーバーです。

Claude、GPT、Gemini などの大規模言語モデルが、安全な API を通じて Nextcloud のデータを操作できるようにします。自然言語で会話するだけで、ノートの作成、カレンダーの管理、連絡先の整理、ファイルの操作などを行えます。

これは、Claude Code や IDE などの外部 MCP クライアント向けに設計された、専用のスタンドアロン MCP サーバーです。Nextcloud とは独立して（Docker、VM、Kubernetes、またはローカル環境で）動作し、Nextcloud アプリ全体で高度な CRUD 操作を提供します。

メモ

Nextcloud 内で AI 機能を使いたい場合は、Nextcloud 独自のアシスタントをこのサーバーに接続できます。詳しくは、以下のNextcloud 内での AIをご覧ください。

ヒント

セルフホストを希望しない場合は、Astrolabe Cloudをご利用ください。この MCP サーバーのマネージドホスティングサービスで、インフラを自分で運用せずにバックグラウンド同期やセマンティック検索などの高度な機能を利用したいユーザーやチームを対象としています。現在開発中です。早期利用者リストへの登録は、ランディングページからお申し込みください。

クイックスタート

uvxを使って、サーバーをローカルで実行します（インストールは不要です）。

NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
  uvx nextcloud-mcp-server run --transport stdio

または、MCP クライアントの設定に直接追加します（例：claude_desktop_config.jsonまたは.claude/settings.json）。

{
  "mcpServers": {
    "nextcloud": {
      "command": "uvx",
      "args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

ヒント

ログインパスワードの代わりに、Nextcloud の設定 > セキュリティ > デバイスとセッションからアプリパスワードを生成して使用してください。

Docker

セマンティック検索を含むすべての機能を利用するには、Docker で実行してください。

docker run -p 127.0.0.1:8000:8000 --rm \
  -e NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
  -e NEXTCLOUD_USERNAME=your_username \
  -e NEXTCLOUD_PASSWORD=your_app_password \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

その後、MCP クライアント（Claude Desktop、IDE、mcp devなど）をhttp://127.0.0.1:8000/mcpに接続します。

Kubernetes については、cbcoutinho/helm-chartsをご覧ください。その他のデプロイ方法と Compose プロファイルについては、docs/installation.mdをご覧ください。

主な機能

• 110 以上の MCP ツール - 10 種類の Nextcloud アプリにわたる包括的な API 対応
• MCP リソース - Nextcloud データを閲覧するための構造化データ URI
• セマンティック検索（実験的） - Notes、Files、News のアイテム、Deck のカード、Mail のメッセージを対象とする、ベクトル検索を活用したオプション機能（Qdrant と Ollama が必要です）
• ドキュメント処理 - 進行状況の通知に対応した、PDF、DOCX、画像からの OCR とテキスト抽出
• 柔軟なデプロイ - Docker、Kubernetes（Helm チャート）、VM、またはローカルインストール
• 本番環境対応の認証 - アプリパスワードを使った Basic Auth、および Login Flow v2 によるマルチユーザー対応。MCP クライアントは OAuth で認証し、サーバーが Nextcloud のアプリパスワードを透過的に処理します
• タグベースのファイル除外 - 設定した Nextcloud システムタグ（EXCLUDED_TAGS）を付けて、機密ファイルやフォルダーを MCP ファイルツールから非表示にできます。詳しくはdocs/configuration.mdをご覧ください
• 複数のトランスポート - streamable-http（デフォルト）と stdio

対応アプリ

アプリ	ツール	機能
Notes	7	完全な CRUD、キーワード検索、セマンティック検索
Calendar	20+	イベント、ToDo（タスク）、繰り返しイベント、参加者、空き状況
Contacts	8	CardDAV の完全サポート、アドレス帳
Files (WebDAV)	14	ファイルシステムへのアクセス、OCR／ドキュメント処理、ファイルのコメント
Deck	15	ボード、スタック、カード、ラベル、割り当て
Cookbook	13	レシピ管理、URL インポート（schema.org）
Tables	5	Nextcloud Tables の行操作
Sharing	10+	共有の作成と管理
News	8	フィード、フォルダー、アイテム、フィードの健全性モニタリング
Mail	13	アカウント、メールボックス、メッセージ、添付ファイル、送信、フラグ（既読／未読、スター）、タグ、移動、削除
Collectives	16	Collective、ページ、タグの完全な CRUD
Talk (spreed)	6	会話の一覧表示、メッセージの読み取り／投稿、既読への変更、参加者の一覧表示
Shopping List	12	リストとアイテム — 1 回の呼び出しでレシピ全体の材料を追加し、アイテムにチェックを付け、チェック済みアイテムを一括削除
Semantic Search	2+	Notes、Files、News のアイテム、Deck のカード、Mail のメッセージをベクトル検索（実験的機能、オプトイン方式、インフラストラクチャが必要）

対応してほしい Nextcloud アプリがほかにもありますか？issue を作成するか、プルリクエストを送ってください！

認証

MCP サーバーはアプリ専用パスワード（Basic Auth）を使用して Nextcloud に認証します。次の 3 つのデプロイモードに対応しています。

モード	最適な用途
シングルユーザー（BasicAuth）	個人利用、開発、シングルユーザーのデプロイ
マルチユーザー（BasicAuth パススルー）	クライアントが Authorization ヘッダーで認証情報を送信するマルチユーザー環境
マルチユーザー（Login Flow v2）	マルチユーザー／ホスト型デプロイ — クライアントは OAuth 経由で MCP サーバーに認証し、サーバーは Nextcloud からユーザーごとのアプリ専用パスワードを取得して透過的に使用します

Nextcloud への直接 OAuth 認証は、user_oidc に対する上流パッチが必要でしたが、マージされなかったため、現在はサポートされていません。Login Flow v2 がマルチユーザーのデプロイでこれに代わり、標準の Nextcloud で動作します。

セットアップ手順については、docs/authentication.md を参照してください。

Nextcloud 内の AI

このサーバーは、Claude Code、IDE、デスクトップクライアントなど、Nextcloud の外部で動作する AI アシスタント向けに構築されています。しかし、Nextcloud には独自のチャット機能であるAssistantアプリがあり、コンテンツへのアクセスを提供する方法が 2 つあります。

Assistant の「AI とチャット」に応答する方法	必要なもの	動作
Context Agent（Nextcloud 提供）	AppAPI と、ExApp を実行するための別コンテナ	Nextcloud に対して処理を実行します — Talk メッセージの送信、イベントの作成などの書き込み操作を、確認ステップ付きで行います
Astrolabe + このサーバー	Astrolabe アプリと、そこからアクセス可能なこのサーバー	自分のドキュメントから回答し、出典を示します。すべての主張に、元となったファイル、ノート、カードへのリンクが付きます。読み取り専用です

Astrolabe は Assistant のエージェントプロバイダーとして自身を登録する Nextcloud アプリです。そのため、AppAPI も追加コンテナも必要ありません — Assistant が Astrolabe と連携し、このサーバーを通じてコンテンツを検索します。各ユーザーの質問はそのユーザー自身の ID で実行されるため、すでに開けるもの以外を他のユーザーが見ることはありません。

両方をインストールしてインスタンスごとに選ぶことも、どちらもインストールしないこともできます。外部の MCP クライアントからこのサーバーを使ううえで、これらは必須ではありません。

セットアップについては、Astrolabe のセットアップガイドを参照してください。比較の背景にあるアーキテクチャの詳細については、docs/comparison-context-agent.mdを参照してください。

セマンティック検索

キーワードではなく意味に基づいて MCP クライアントが Nextcloud のコンテンツを検索できる、実験的な RAG パイプラインです。「car」と検索すると、「vehicle」や「transportation」に関するノートも表示されます。デフォルトでは無効です（ENABLE_SEMANTIC_SEARCH=false）。semantic エクストラ（pip install 'nextcloud-mcp-server[semantic]'、Docker イメージに含まれています）、ベクトルデータベース、埋め込みサービスが必要です。docs/semantic-search-architecture.md および docs/configuration.md をご覧ください。

検索結果の並べ替え、つまりクロスエンコーダーを使って統合された順位スコアを調整済みの関連度スコアに変換する方法については、docs/reranking.md をご覧ください。Infinity/vLLM を使ったセルフホスト、または Cohere のホスト型サービスを利用でき、埋め込みゲートウェイの有無も選択できます。

ヒント

Qdrant や埋め込みサービスを実行せずに使いたいですか？ Astrolabe Cloud（開発中）は、セマンティック検索とバックグラウンド同期をマネージドサービスとして提供します。

ドキュメント

• インストール — Docker、Compose プロファイル、ローカル環境、VM
• 設定 — 環境変数、ドキュメント処理、セマンティック検索の設定
• 認証 — Basic Auth、Login Flow v2
• サーバーの実行 — 起動、管理、トラブルシューティング
• アプリのドキュメント — アプリごとのガイド（Notes、Calendar、Contacts、WebDAV、Deck、Cookbook、Tables）
• セマンティック検索のアーキテクチャ + ベクトル同期 UI
• リランキング — クロスエンコーダーによる関連度スコアリング（Infinity、vLLM、Cohere）。埋め込みゲートウェイは不要です
• Login Flow v2 — 推奨されるマルチユーザー設定（アーキテクチャ、環境変数、スコープのリファレンス、トラブルシューティング）
• トラブルシューティング · Context Agent との比較

コントリビューション

コントリビューションを歓迎します！

• バグの報告や機能のリクエスト：GitHub Issues
• 改善の提案：Pull Requests
• 開発ガイドライン：CLAUDE.md

セキュリティ

セキュリティ上の問題を見つけた場合は、公開の GitHub Issue を作成しないでください。 GitHub の非公開の脆弱性報告を利用するか、GitHub を利用できない場合は [email protected] までメールでご連絡ください。詳細は SECURITY.md をご覧ください。

ライセンス

このプロジェクトは AGPL-3.0 License の下でライセンスされています。詳細は LICENSE をご覧ください。

スター履歴

参考資料

• Model Context Protocol
• MCP Python SDK
• Nextcloud