Couchbase

Couchbase MCP Server

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

Couchbase MCP Server は、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 Server のフルマネージド版である Capella の無料枠を使用することです。手順 に従って、サンプルデータセットのいずれかをインポートするか、独自のデータをインポートできます。
• サーバーを実行するために uv がインストールされていること。
• サーバーを Claude に接続するために、Claude Desktop などの MCP クライアント がインストールされていること。手順は Claude Desktop と Cursor 向けに提供されています。他の MCP クライアントも使用できます。

設定

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

PyPI からの実行

MCP Server 用のビルド済み 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 Server を使用している場合は、既存の mcpServers オブジェクトに追加できます。

ソースからの実行

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

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

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 Server を使用している場合は、既存の mcpServers オブジェクトに追加できます。

MCP Server の追加設定

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

読み取り専用モードの設定

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

• true（デフォルト）の場合: すべての書き込み操作（KV および Query）が無効になります。KV 書き込みツール（upsert、insert、replace、delete）は読み込まれず、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 を無効化しても、以下の条件を満たさない限り、SQL++ DML文（INSERT、UPDATE、DELETE、MERGE）を使用する run_sql_plus_plus_query ツールを介してデータ変更が行われる可能性があります。

• 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）が書き込まれます。

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

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

クライアント固有の設定

ストリーミング可能HTTPトランスポートモード

MCPサーバーは、ストリーミング可能HTTP トランスポートモードで実行できます。これにより、複数のクライアントがHTTP経由で同じサーバーインスタンスに接続できます。 このモードでMCPサーバーに接続する前に、MCPクライアント がストリーミング可能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などのストリーミング可能HTTPトランスポートモードをサポートするMCPクライアントで使用できます。

MCPクライアント設定

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

SSEトランスポートモード

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

注: SSEモードはMCPによって 非推奨 になりました。ストリーミング可能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変更ツール）。完全なアクセスには両方が必要です。

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カタログ の一部です。

イメージのビルド

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の見解を反映していない可能性があります。
• お客様は、大規模言語モデルおよび関連テクノロジーを使用するかどうかを決定し、その使用に関するライセンス条項、利用規約、および組織のポリシーを遵守する責任を単独で負います。

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

• ソースから実行する場合は、設定内の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を使用したコードのリンティングとフォーマット
• プレコミットフックのインストール
• プロジェクト構造の概要
• 開発ワークフローとプラクティス

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

# 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内で行っていただきますようお願いいたします。

皆様のご協力により、共に前進できます — ありがとうございます！