Couchbase MCP サーバー

LLM が Couchbase クラスターと直接対話できるようにする Couchbase のMCPサーバー実装。

特徴

指定されたバケット内のすべてのスコープとコレクションのリストを取得します
コレクションの構造を取得する
指定されたスコープとコレクションからIDでドキュメントを取得する
指定されたスコープとコレクションに ID でドキュメントをアップサートする
指定されたスコープとコレクションから ID でドキュメントを削除します
指定されたスコープでSQL++クエリを実行する
- MCPサーバーには、 READ_ONLY_QUERY_MODEオプションがあります。これはデフォルトでtrueに設定されており、データや基礎となるコレクション構造を変更するSQL++クエリの実行を無効にします。ただし、ドキュメントはIDによって更新できます。

前提条件

Python 3.10 以上。
稼働中のCouchbaseクラスター。始める最も簡単な方法は、Couchbaseサーバーのフルマネージド版であるCapellaの無料プランを利用することです。手順に従ってサンプルデータセットをインポートするか、独自のデータセットをインポートしてください。
サーバーを実行するためにuvがインストールされています。
サーバーをClaudeに接続するには、 Claude DesktopなどのMCPクライアントをインストールする必要があります。この手順はClaude DesktopとCursorを対象としています。他のMCPクライアントでも同様に使用できます。

構成

リポジトリをローカルマシンにクローンします。

git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git

MCP クライアントのサーバー構成

これは、Claude Desktop、Cursor、Windsurf Editor などの MCP クライアントに共通する構成です。

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

サーバーは環境変数を使用して設定できます。以下の変数がサポートされています。

CB_CONNECTION_STRING : Couchbaseクラスタへの接続文字列
CB_USERNAME : 接続に使用するバケットへのアクセス権を持つユーザー名
CB_PASSWORD : 接続するユーザー名のパスワード
CB_BUCKET_NAME : サーバーがアクセスするバケットの名前
READ_ONLY_QUERY_MODE : データの変更を許可するSQL++クエリを許可するかどうかを設定する設定です。デフォルトではTrueに設定されています。
path/to/cloned/repo/mcp-server-couchbase/ローカルマシン上のクローンリポジトリへのパスです。末尾のスラッシュを忘れないでください。

注: クライアントで他の MCP サーバーを使用している場合は、それを既存のmcpServersオブジェクトに追加できます。

クロードデスクトップ

Couchbase MCPサーバーをClaude Desktop MCPクライアントで使用するには、以下の手順に従ってください。

設定ファイルを編集することで、MCPサーバーをClaude Desktopに追加できるようになりました。詳細な手順については、 MCPクイックスタートガイドをご覧ください。
- Macの場合、設定ファイルは~/Library/Application Support/Claude/claude_desktop_config.jsonにあります。
- Windowsでは、構成ファイルは%APPDATA%\Claude\claude_desktop_config.jsonにあります。
構成ファイルを開き、 mcpServersセクションに構成を追加します。
変更を適用するには、Claude Desktop を再起動します。
Claude Desktop のサーバーを使用して、自然言語で Couchbase クラスターに対してクエリを実行し、ドキュメントに対して CRUD 操作を実行できるようになりました。

クロードデスクトップログ

Claude Desktop のログは次の場所にあります。

MacOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\Logs

ログは、接続の問題やMCPサーバー設定に関するその他の問題を診断するために使用できます。詳細については、公式ドキュメントをご覧ください。

カーソル

Cursor で Couchbase MCP サーバーを使用するには、以下の手順に従います。

マシンにCursorをインストールします。
Cursorで、「Cursor > Cursor Settings > MCP > 新しいグローバルMCPサーバーを追加」に進みます。また、CursorからMCPサーバーの設定を行う方法については、ドキュメントをご覧ください。
同じ設定を指定します。mcpServers の親キーの下にサーバー設定を追加する必要がある場合があります。
設定を保存します。
MCPサーバーリストに追加されたサーバーとしてCouchbaseが表示されます。サーバーが有効になっているかどうかを確認するには、リストを更新してください。
Cursor で Couchbase MCP サーバーを使用して、自然言語で Couchbase クラスターをクエリし、ドキュメントに対して CRUD 操作を実行できるようになりました。

MCP と Cursor の統合の詳細については、公式の Cursor MCP ドキュメントを参照してください。

カーソルログ

Cursorの下部パネルで「出力」をクリックし、ドロップダウンメニューから「Cursor MCP」を選択すると、サーバーログが表示されます。これにより、接続の問題やMCPサーバー設定に関するその他の問題の診断に役立ちます。

ウィンドサーフィンエディター

Windsurf Editorで Couchbase MCP サーバーを使用するには、以下の手順に従います。

マシンにWindsurf Editorをインストールします。
Windsurfエディターで、「コマンドパレット」>「Windsurf MCP設定パネル」または「Windsurf - 設定」>「詳細設定」>「カスケード」>「モデルコンテキストプロトコル（MCP）サーバー」に移動します。設定の詳細については、公式ドキュメントを参照してください。
「サーバーを追加」をクリックし、「カスタムサーバーを追加」をクリックします。エディタで開いた設定に、上記のCouchbase MCP Serverの設定を追加します。
設定を保存します。
詳細設定のMCPサーバーリストに、追加されたサーバーとしてCouchbaseが表示されます。サーバーが有効になっているかどうかを確認するには、更新してください。
Windsurf エディターで Couchbase MCP サーバーを使用して、自然言語で Couchbase クラスターをクエリし、ドキュメントに対して CRUD 操作を実行できるようになりました。

Windsurf Editor と MCP の統合の詳細については、公式のWindsurf MCP ドキュメントを参照してください。

SSE サーバーモード

MCP サーバーをServer-Sent Events (SSE)トランスポートモードで実行するオプションがあります。

使用法

デフォルトでは、MCP サーバーはポート 8080 で実行されますが、これはFASTMCP_PORT環境変数を使用して構成できます。

uv run src/mcp_server.py --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

サーバーはhttp://localhost:8080/sseで利用できます。これは、SSEトランスポートモードをサポートするMCPクライアントで使用できます。

Dockerイメージ

MCPサーバーはDockerコンテナとして構築・実行することもできます。ビルド済みのイメージはDockerHubで入手できます。

docker built -t mcp/couchbase .

ランニング

MCPサーバーは、Couchbaseの設定に使用されている環境変数を使用して実行できます。環境変数は、設定セクションで説明されているものと同じです。

docker run -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

LLMに関連するリスク

大規模言語モデルや同様のテクノロジーの使用には、不正確または有害な出力が生じる可能性など、リスクが伴います。
Couchbase は、このような出力の品質や正確性を検討または評価しておらず、このような出力は Couchbase の見解を反映していない可能性があります。
大規模言語モデルおよび関連テクノロジーを使用するかどうかを決定し、その使用を規定するライセンス条項、使用条件、および組織のポリシーに準拠する責任は、お客様のみが負います。

マネージドMCPサーバー

Couchbase MCP サーバーは、 Smithery.aiを介してエージェントアプリケーション内の管理対象サーバーとして使用することもできます。

トラブルシューティングのヒント

構成内の MCP サーバーリポジトリへのパスが正しいことを確認します。
Couchbase 接続文字列、データベースのユーザー名、パスワード、バケット名が正しいことを確認します。
Couchbase Capella を使用する場合は、MCP サーバーが実行されているマシンからクラスターにアクセスできることを確認してください。
データベースユーザーが指定されたバケットにアクセスするための適切な権限を持っていることを確認します。
UVパッケージマネージャーが正しくインストールされ、アクセス可能であることを確認してください。設定のcommandフィールドにUVへの絶対パスを指定する必要がある場合があります。
MCPサーバーの問題を示す可能性のあるエラーや警告がないか、ログを確認してください。サーバーログはmcp-server-couchbase.logという名前で保存されています。

📢 サポートポリシー

このプロジェクトにご興味を持っていただき、誠にありがとうございます。
このプロジェクトはコミュニティによって維持されており、サポートチームによって正式にサポートされていません。

ヘルプが必要な場合、バグを発見した場合、または改善に貢献したい場合は、ここ、つまりGitHub の問題を開くのが最適です。
弊社のサポートポータルでは、このプロジェクトに関連するリクエストには対応できませんので、お問い合わせはすべて GitHub 内で行っていただきますようお願いいたします。

皆様のご協力のおかげで、私たちは共に前進することができます。ありがとうございます!

Integrations