Couchbase

Couchbase MCP Server

Couchbase MCP Server は、セルフホスト型の MCP サーバーで、AI エージェントが Capella または自己管理環境でホストされている Couchbase クラスターに接続し、そのデータと対話できるようにします。クラスターのヘルス、データスキーマ、キーバリュー、クエリ、パフォーマンスなどのカテゴリにわたるツールを提供し、読み取り専用モードと細かなツール無効化による安全制御を備えています。STDIO トランスポートと Streamable HTTP トランスポートの両方をサポートしています。

Couchbase MCP サーバーは、Python Package Index (PyPI) パッケージとして、また Docker を介して配布されています。 Couchbase MCP Server のエンタープライズサポートは、Couchbase AI Data Plane のライセンスを取得することで利用できます。これにより、Couchbase Agent Memory および Couchbase Agent Catalog の利用とエンタープライズサポートも受けられます。

完全なドキュメントについては、mcp-server.couchbase.com をご覧ください。

機能/ツール

クラスターセットアップとヘルスツール

データモデルとスキーマ検出ツール

ドキュメント KV 操作ツール

クエリとインデックスツール

クエリパフォーマンス分析ツール

前提条件

• Python 3.10 以降。
• 実行中の Couchbase クラスター。最も簡単な開始方法は、Couchbase サーバーのフルマネージド版である Capella の無料ティアを使用することです。手順 に従ってサンプルデータセットのいずれかをインポートするか、独自のデータをインポートできます。
• サーバーを実行するために uv がインストールされていること。
• サーバーを Claude に接続するための Claude Desktop などの MCP クライアント がインストールされていること。手順は Claude Desktop と Cursor 向けに提供されています。他の MCP クライアントも使用できます。

設定

MCP サーバーは、ビルド済みの PyPI パッケージまたは uv を使用したソースのいずれかから実行できます。

PyPI から実行する

MCP サーバー用のビルド済み PyPI パッケージ を公開しています。

MCP クライアント向けビルド済みパッケージを使用したサーバー設定

基本認証

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

または

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

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

ソースから実行する

MCP サーバーは、このリポジトリを使用してソースから実行できます。

リポジトリをローカルマシンにクローンする

git clone https://github.com/couchbase/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"
      }
    }
  }
}

注：path/to/cloned/repo/mcp-server-couchbase/ はローカルマシン上のクローンしたリポジトリへのパスである必要があります。末尾のスラッシュを忘れないでください！

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

MCP サーバーの追加設定

サーバーは環境変数またはコマンドライン引数を使用して設定できます：

読み取り専用モードの構成

**CB_MCP_READ_ONLY_MODE**は書き込み操作を制御する単一のスイッチです:

• trueの場合（デフォルト）: すべての書き込み操作（KV、Query、スコープ/コレクション管理、インデックス管理）が無効になります。KV書き込みツール（upsert、insert、replace、delete、sub-document mutate）、スコープ/コレクション管理書き込みツール（create_scope、create_collection、delete_scope、delete_collection）、インデックス書き込みツール（create_index、build_index、drop_index）はロードされず、LLMが利用できません。また、データや構造を変更するSQL++クエリはブロックされます。
• falseの場合: KV、スコープ/コレクション管理、インデックス書き込みツールがロードされ、SQL++のデータ/構造変更クエリが許可されます。

これは、LLMによる不意のデータ変更を防ぐための推奨される安全なデフォルトです。

注: 認証には、ユーザー名とパスワード、またはクライアント証明書とキーのパスのいずれかが必要です。オプションで、サーバー証明書の検証に使用されるCAルート証明書のパスを指定できます。 クライアント証明書とキーのパス、およびユーザー名とパスワードの両方が指定された場合、認証にはクライアント証明書が使用されます。

ツールの無効化

特定のツールを無効にして、MCPクライアントにロード・公開されないようにすることができます。無効化されたツールはツールディスカバリに表示されず、LLMから呼び出すこともできません。

サポートされる形式

カンマ区切りリスト:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

ファイルパス（1行に1つのツール名）:

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

ファイル形式（例: disabled_tools.txt）:

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

#で始まる行はコメントとして扱われ、無視されます。

MCPクライアント設定の例

カンマ区切りリストを使用:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

ファイルパスを使用（多数のツールに推奨）:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

重要なセキュリティに関する注意

警告: ツールの無効化だけでは、特定の操作を実行できないことを保証するものではありません。基盤となるデータベースユーザーのRBAC（ロールベースアクセス制御）権限が権威あるセキュリティ制御です。

たとえば、upsert_document_by_idとdelete_document_by_idを無効にしても、以下の場合を除き、run_sql_plus_plus_queryツールを使用したSQL++ DMLステートメント（INSERT、UPDATE、DELETE、MERGE）によってデータ変更が発生する可能性があります:

• CB_MCP_READ_ONLY_MODEがtrue（デフォルト）に設定されている、または
• データベースユーザーにデータ変更に必要なRBAC権限がない

ベストプラクティス: 主要なセキュリティ対策として、Couchbaseユーザー資格情報に適切なRBAC権限を常に構成してください。ツールの無効化は、LLMの動作を導き攻撃対象領域を減らすための追加レイヤーとして使用し、唯一のセキュリティ制御としては使用しないでください。

ツール呼び出しのエリシテーション/確認

特定のツールについて、実行前に明示的なユーザー確認を要求できます（MCPクライアントがエリシテーションをサポートしている場合）。

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-toolsは以下の形式をサポートします:

• カンマ区切りリスト
• ファイルパス（1行に1つのツール名、#コメント対応）

例:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

リストされたツールが呼び出された場合:

• クライアントがエリシテーションをサポートしている場合、ユーザーに確認を求めます。
• クライアントがエリシテーションをサポートしていない場合、後方互換性のため、確認なしでツールが実行されます。

サーバーのバージョンを確認するには、以下を使用します:

uvx couchbase-mcp-server --version

ロギング

MCPサーバーはデフォルトでstderrにログを出力します。ロギングは追加設定にリストされているCB_MCP_LOG_*変数で構成されます:

• CB_MCP_LOG_LEVEL — ログの量: info（デフォルト）はライフサイクルイベントとツール呼び出しをログし、debugは詳細な内部情報を追加し、offはすべてのロギングを無効にします。
• CB_MCP_LOG_SINKS — ログの出力先: stderr（デフォルト）、レベル別ローテーションファイル（file）、または両方。fileの場合、CB_MCP_LOG_FILEで設定されたパスにレベルごとに1つのファイルが書き込まれます（例: mcp_server.info.logとmcp_server.error.log）。
• ローテーションサイズ — CB_MCP_LOG_ROTATION_MAX_SIZE_MBは各レベル別ファイルがローテーションするグローバルサイズ（MB単位）です。個々のレベルはCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB（ERROR/WARNING/INFO/DEBUG）で上書きできます。これもMB単位で、未設定の場合はグローバル値を継承します。0（グローバルまたはレベル別）のサイズは無効で、起動時の警告とともにデフォルト（1 MB）にフォールバックします。CB_MCP_LOG_MAX_BYTES（バイト）は非推奨ですが、後方互換性のため引き続き有効です。CB_MCP_LOG_ROTATION_MAX_SIZE_MBも設定されている場合は無視され、起動時に非推奨の警告が表示されます。
• 保持 — CB_MCP_LOG_RETENTION_BACKUP_COUNTはレベルごとに保持されるローテーション済みバックアップ数（ライブファイルを除く）を設定します。デフォルトの1は以前の動作を維持します。個々のレベルはCB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT（ERROR/WARNING/INFO/DEBUG）で上書きでき、未設定の場合はグローバル値を継承します。あるレベルについて0に設定すると、そのレベルのライブファイルのみが保持されます。ローテーションサイズの上限は依然として適用されます（ロールオーバー時にリセットされ、バックアップされません）。
• サーバー設定スナップショット — fileシンクがアクティブな場合、ワンショットレコード（OS、Python、依存関係のバージョン、トランスポート、解決済みのロギング設定、および編集済みサーバー設定）がJSONとして専用のmcp_server_config.log.jsonファイル（CB_MCP_LOG_FILEベースから派生）に書き込まれます。起動のたびに上書きされるため、サポートは常に現在の設定を保持でき、ローテーションログからスクロールアウトされることはありません。

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

詳細については、ドキュメントを参照してください。

クライアント固有の設定

Streamable HTTP トランスポートモード

MCP サーバーは、複数のクライアントが HTTP 経由で同じサーバーインスタンスに接続できる Streamable HTTP トランスポートモードで実行できます。 このモードで MCP サーバーに接続する前に、MCP クライアント が streamable http トランスポートをサポートしているかどうかを確認してください。

注：このトランスポートでは OAuth 2.1 認証がサポートされています。OAuth 2.1 認証 を参照してください。OAuth が設定されていない場合、HTTP エンドポイントは認証されません。

使用方法

デフォルトでは、MCP サーバーはポート 8000 で実行されますが、これは --port または CB_MCP_PORT 環境変数を使用して設定できます。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

サーバーは http://localhost:8000/mcp で利用可能になります。これは、Cursor などの streamable http トランスポートモードをサポートする MCP クライアントで使用できます。

MCP クライアント設定

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE トランスポートモード

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

注：SSE モードは MCP によって 非推奨 になりました。Streamable HTTP をサポートしています。

SSE：使用方法

デフォルトでは、MCP サーバーはポート 8000 で実行されますが、これは --port または CB_MCP_PORT 環境変数を使用して設定できます。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

サーバーは http://localhost:8000/sse で利用可能になります。これは、Cursor などの SSE トランスポートモードをサポートする MCP クライアントで使用できます。

SSE：MCP クライアント設定

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

OAuth 2.1 認証

--transport=http で実行する場合、MCP サーバーは OAuth 2.1 リソースサーバー として機能できます。つまり、受信したベアラー JWT を ID プロバイダーの JWKS に対して検証します。プロバイダーに依存しません（JWKS を公開する任意の OAuth 2.1 / OIDC プロバイダー — Auth0、Okta、Keycloak、AWS Cognito、Microsoft Entra など）。トークンを発行したり、ユーザーを管理したりすることは ありません。OAuth 設定は stdio では無視されます。

OAuth は、追加設定 に記載されている CB_MCP_OAUTH_* 変数で設定されます：

• OAuth は、CB_MCP_OAUTH_JWT_JWKS_URI、CB_MCP_OAUTH_JWT_ISSUER、CB_MCP_OAUTH_JWT_AUDIENCE の 3 つすべてが設定されている場合にのみ有効になります。一部のみを設定すると、起動時に失敗します。
• CB_MCP_OAUTH_MCP_BASE_URL を設定すると、RFC 9728 Protected Resource Metadata も公開され、PRM 対応クライアントが認可サーバーを検出できるようになります。
• アクセスは、トークンの scope/scp クレームから読み取られる 2 つのスコープによって制御されます：couchbase-mcp:read（SQL++ を含む読み取りツール）と couchbase-mcp:write（書き込みツール：KV ミューテーション、スコープ/コレクション管理、インデックス管理）。フルアクセスには両方が必要です。IdP がこれらの標準ラベルを発行できない場合は、CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL で上書きします。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

詳細については、ドキュメント を参照してください。

Docker イメージ

MCP サーバーは、Docker コンテナとしてビルドして実行することもできます。ビルド済みイメージは DockerHub で見つけるか、docker pull docker.io/couchbase/mcp-server:latest でプルできます。

あるいは、Docker MCP Catalog の一部でもあります。

イメージのビルド

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

実行

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

独立した Docker コンテナ

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

CB_MCP_PORT および CB_MCP_HOST 環境変数は、http や sse などの HTTP トランスポートモードの場合にのみ適用されます。

Docker：MCP クライアント設定

Docker イメージは、次の設定で stdio トランスポートモードで使用できます。

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

注

• couchbase_connection_string の値は、Couchbase サーバーが同じホストマシン、別の Docker コンテナ、またはリモートホストのいずれで実行されているかによって異なります。Couchbase サーバーがホストマシンで実行されている場合、接続文字列はおそらく couchbase://host.docker.internal の形式になります。詳細については、docker ドキュメント を参照してください。
• コンテナのネットワーキングは、--network=<your_network> オプションを使用して指定できます。選択するネットワークは環境によって異なります。デフォルトは bridge です。詳細については、docker のネットワークドライバー を参照してください。

LLM に関連するリスク

• 大規模言語モデルおよび類似のテクノロジーの使用には、不正確または有害な出力の可能性を含むリスクが伴います。
• Couchbase は、そのような出力の品質や正確性をレビューまたは評価せず、そのような出力が Couchbase の見解を反映していない場合があります。
• 大規模言語モデルおよび関連テクノロジーを使用するかどうかの決定、およびライセンス条項、利用規約、およびそれらの使用を管理する組織のポリシーへの準拠については、お客様が単独で責任を負います。

使用状況データの収集

この製品は、使用状況およびパフォーマンスデータ（製品名やバージョンなど）とブラウザ情報（IP アドレスなど）を自動的に収集します（総称して「使用状況データ」）。Couchbase は、使用状況データを、お客様が Couchbase に提供する可能性のあるその他のデータ（ユーザー名やメールアドレスなど）とともに、製品の開発と改善、および営業およびマーケティングプログラムの情報提供に使用します。Couchbase 製品に保存されたデータにはアクセスまたは収集しません。使用状況データを使用して、集計された使用パターンを理解し、製品をお客様にとってより有用なものにします。Couchbase が情報を収集、保護、処理する方法の詳細については、https://www.couchbase.com/privacy-policy. で閲覧できる Couchbase プライバシーポリシーを参照してください。

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

• ソースから実行する場合は、設定内のMCPサーバーリポジトリへのパスが正しいことを確認してください。
• Couchbaseの接続文字列、データベースのユーザー名、パスワード、または証明書へのパスが正しいことを確認してください。
• Couchbase Capellaを使用する場合は、MCPサーバーが実行されているマシンからクラスターにアクセス可能であることを確認してください。
• データベースユーザーが少なくとも1つのバケットにアクセスするための適切な権限を持っていることを確認してください。
• uvパッケージマネージャーが正しくインストールされ、アクセス可能であることを確認してください。設定のcommandフィールドにuv/uvxへの絶対パスを指定する必要がある場合があります。
• MCPサーバーの問題を示す可能性のあるエラーや警告がないかログを確認してください。ログの場所はMCPクライアントによって異なります。
• ローカルのMCPサーバーリポジトリを更新した後にソースからMCPサーバーを実行する際に問題が発生する場合は、uv syncを実行して依存関係を更新してみてください。

統合テスト

サーバーが期待されるツールを公開し、それらがデモのCouchbaseクラスターに対して呼び出し可能であることを検証するための高レベルのMCP統合テストを提供しています。

1. デモクラスターの認証情報をエクスポートします：
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • オプション：CB_MCP_TEST_BUCKET（テスト中にプローブするバケット）
2. テストを実行します：

uv run pytest tests/ -v

👩‍💻 コントリビューション

コミュニティからの貢献を歓迎します！バグの修正、機能の追加、ドキュメントの改善など、どのような貢献も歓迎します。

ヘルプが必要な場合、バグを見つけた場合、または改善に貢献したい場合は、GitHub issueを開くことでここで行うのが最適です。

開発者の方へ

コードの貢献や開発環境のセットアップに興味がある場合：

📖 包括的な開発者セットアップ手順については、CONTRIBUTING.mdを参照してください。以下を含みます：

• uvを使用した開発環境のセットアップ
• Ruffを使用したコードのリンティングとフォーマット
• Pre-commitフックのインストール
• プロジェクト構造の概要
• 開発ワークフローとプラクティス

コントリビューター向けクイックスタート

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 サポートポリシー

このプロジェクトへの関心を心から感謝します！ このプロジェクトはCouchbaseコミュニティメンテナンスであり、サポートチームによる公式サポートは提供されていません。ただし、当社のエンジニアはこのリポジトリを積極的に監視・保守しており、ベストエフォートで問題の解決に努めます。

サポートポータルではこのプロジェクトに関連するリクエストに対応できませんので、すべてのお問い合わせはGitHub内で行っていただくようお願いいたします。

皆様の協力が私たち全員の前進につながります。ありがとうございます！