Nextcloud MCPサーバー

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

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

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

[!NOTE] Nextcloud内のAI機能をお探しですか？ NextcloudはContext Agentも提供しており、これはAssistantアプリを強化し、Nextcloud内でExAppとして動作します。ユースケースの詳細な比較については、docs/comparison-context-agent.mdを参照してください。

クイックスタート (Docker)

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

# 1. Create a minimal configuration
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. Start the server
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. Test the connection
curl http://127.0.0.1:8000/health/ready

# 4. Connect to the endpoint
http://127.0.0.1:8000/sse

# Or with --transport streamable-http
http://127.0.0.1:8000/mcp

Docker Composeプロファイル（開発/テスト用）：

docker compose --profile single-user up -d       # Port 8000
docker compose --profile multi-user-basic up -d   # Port 8003
docker compose --profile oauth up -d              # Port 8001
docker compose --profile login-flow up -d         # Port 8004

次のステップ：

• MCPクライアント（Claude Desktop、IDE、mcp devなど）を接続する

• その他のデプロイオプション（ローカル、Kubernetes）については、docs/installation.mdを参照してください

Related MCP server: Nextcloud MCP Server

主な機能

• 90以上のMCPツール - 8つのNextcloudアプリにわたる包括的なAPIカバレッジ

• MCPリソース - Nextcloudデータをブラウズするための構造化データURI

• セマンティック検索（実験的） - ノート、ファイル、ニュースアイテム、Deckカード向けのベクトルベースの検索（Qdrant + Ollamaが必要）

• ドキュメント処理 - PDF、DOCX、画像からのOCRおよびテキスト抽出（進捗通知付き）

• 柔軟なデプロイ - Docker、Kubernetes (Helm)、VM、またはローカルインストール

• 本番環境対応の認証 - アプリパスワードを使用したBasic認証（推奨）またはOAuth2/OIDC（実験的）

• 複数のトランスポート - SSE、HTTP、およびストリーミング可能なHTTPをサポート

対応アプリ

他のNextcloudアプリのサポートをご希望ですか？Issueを作成するか、プルリクエストを送信してください！

認証

[!IMPORTANT] OAuth2/OIDCは実験的であり、user_oidcアプリへの手動パッチが必要です：

• 必要なパッチ: Bearerトークンのサポート (issue #1221)

• 影響: パッチがない場合、ほとんどのアプリ固有のAPIは401エラーで失敗します

• 推奨: アップストリームのパッチがマージされるまでは、本番環境ではBasic認証を使用してください

パッチのステータスと回避策については、docs/oauth-upstream-status.mdを参照してください。

推奨: アプリ固有のパスワードを使用したBasic認証は、安全で本番環境に対応した認証を提供します。セットアップの詳細とOAuth設定については、docs/authentication.mdを参照してください。

認証モード

サーバーは4つの認証モードをサポートしています：

シングルユーザー（BasicAuth）：

• すべてのMCPクライアントで共有される1組の資格情報

• シンプルなセットアップ：環境変数にユーザー名とアプリパスワードを設定

• すべてのクライアントが同じユーザーとしてNextcloudにアクセス

• 用途：個人利用、開発、シングルユーザーデプロイ

マルチユーザー（BasicAuthパススルー）：

• MCPクライアントがAuthorizationヘッダー経由で資格情報を送信

• サーバーがNextcloudにパススルー（デフォルトでステートレス）

• バックグラウンド操作のためのオプションのオフラインアクセス (ENABLE_MULTI_USER_BASIC_AUTH=true)

• 用途：OAuthインフラのないマルチユーザーセットアップ

マルチユーザー（OAuth）：

• 各MCPクライアントが自身のNextcloudアカウントで個別に認証

• ユーザーごとのスコープと権限（クライアントは許可されたツールのみを表示）

• より安全：トークンは期限切れになり、資格情報がサーバーと共有されることはありません

• 用途：チーム、マルチユーザーデプロイ、複数のユーザーがいる本番環境

• 必要条件：user_oidcアプリへのパッチ（実験的）

マルチユーザー（ログインフローv2）：

• Nextcloudのネイティブなログインフローv2を使用して、ユーザーごとのアプリパスワードを取得

• OAuthパッチは不要 — 標準のNextcloudで動作

• 各ユーザーがブラウザ経由で認証し、サーバーがアプリパスワードを管理

• 用途：OAuthインフラのないマルチユーザーデプロイ (ENABLE_LOGIN_FLOW=true)

• 実験的：詳細についてはADR-022を参照

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

セマンティック検索

このサーバーは、MCPクライアントがキーワードだけでなく意味に基づいてNextcloud内の情報を検索できるようにする、実験的なRAGパイプラインを提供します。「machine learning」という正確な単語が含まれている場合のみ一致させるのではなく、「neural networks」、「AI models」、「deep learning」が意味的に関連する概念であることを理解します。

例：

• キーワード検索: 「car」とクエリすると、「car」を含むノートのみが見つかる

• セマンティック検索: 「car」とクエリすると、「automobile」、「vehicle」、「sedan」、「transportation」に関するノートも見つかる

これにより、自然言語でのクエリが可能になり、Nextcloudのノート全体で関連コンテンツを発見しやすくなります。

[!NOTE] セマンティック検索は実験的であり、オプトインです：

• デフォルトでは無効 (ENABLE_SEMANTIC_SEARCH=false)

• 現在はNotesアプリのみサポート（マルチアプリサポートを計画中）

• 追加のインフラが必要：ベクトルデータベース + 埋め込みサービス

• 回答生成 (nc_semantic_search_answer) にはMCPクライアントのサンプリングサポートが必要

アーキテクチャの詳細についてはdocs/semantic-search-architecture.mdを、セットアップ手順についてはdocs/configuration.mdを参照してください。

ドキュメント

はじめに

• インストール - Docker、Kubernetes、ローカル、またはVMデプロイ

• 設定 - 環境変数と高度なオプション

• 認証 - Basic認証とOAuth2/OIDCのセットアップ

• サーバーの実行 - 起動、管理、トラブルシューティング

機能

• アプリドキュメント - Notes、Calendar、Contacts、WebDAV、Deck、Cookbook、Tables

• ドキュメント処理 - OCRとテキスト抽出のセットアップ

• セマンティック検索アーキテクチャ - 実験的なベクトル検索（Notes、Files、ニュースアイテム、Deckカード；オプトイン）

• ベクトル同期UIガイド - セマンティック検索の可視化とテストのためのブラウザインターフェース

高度なトピック

• OAuthアーキテクチャ - OAuthの仕組み（実験的）

• OAuthクイックスタート - 5分でできるOAuthセットアップ

• OAuthセットアップガイド - 詳細なOAuth設定

• トラブルシューティング - 一般的な問題と解決策

• Context Agentとの比較 - 各アプローチの使い分け

例

ノートの作成

AI: "Create a note called 'Meeting Notes' with today's agenda"
→ Uses nc_notes_create_note tool

レシピのインポート

AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction

会議のスケジュール

AI: "Schedule a team meeting for next Tuesday at 2pm"
→ Uses nc_calendar_create_event tool

ファイルの管理

AI: "Create a folder called 'Project X' and move all PDFs there"
→ Uses nc_webdav_create_directory and nc_webdav_move tools

セマンティック検索（実験的、オプトイン）

AI: "Find notes related to machine learning concepts"
→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)

注: 引用付きのAI生成回答については、nc_semantic_search_answerを使用してください（サンプリングサポートを備えたMCPクライアントが必要です）。

貢献

貢献を歓迎します！

• バグ報告や機能リクエスト: GitHub Issues

• 改善の提案: Pull Requests

• 開発ガイドライン: CLAUDE.md

セキュリティ

このプロジェクトはセキュリティを重視しています：

• アプリ固有のパスワードを使用した本番環境対応のBasic認証

• OAuth2/OIDCサポート（実験的、アップストリームのパッチが必要）

• ユーザーごとのアクセストークン

• OAuthモードでの資格情報の保存なし

• 定期的なセキュリティ評価

セキュリティ上の問題を見つけた場合は、メンテナに非公開で報告してください。

ライセンス

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

スターの履歴

参照

• Model Context Protocol

• MCP Python SDK

• Nextcloud