Couchbase
公式Couchbaseクラスターに保存されたデータと自然言語で対話します。
Couchbase MCPで何ができますか?
- クラスターデータの確認 — バケット、スコープ、コレクションを一覧表示し、
ordersのようなコレクションのスキーマを推測します。 - SQL++ クエリの実行 — バケットとスコープに対して読み取り専用の SQL++ クエリを実行し、クエリプランを説明します。
- ドキュメントの確認 — ID でドキュメントを取得するか、ドキュメント全体を読み込まずに特定のサブドキュメントパスを読み取ります。
- クラスターヘルスの確認 — クラスターのヘルス、実行中のサービス、接続診断を報告します。
- クエリパフォーマンスの分析 — 実行時間が最も長いクエリ、実行頻度が最も高いクエリ、またはカバリングインデックスを使用しないクエリを特定します。
- 検索とベクトルクエリ — 設定済みのインデックスに対して全文検索とベクトル類似度クエリを実行します。
ドキュメント
Couchbase MCP Server
Couchbase MCP Server は、AI エージェントが Couchbase Server(Capella 上でホストされている場合も、セルフマネージドの場合も)または Operational Insights Enterprise のデータに接続して操作できる、セルフホスト型の MCP Server です。Cluster Health、Data Schema、Query などのカテゴリにわたるツールを提供し、読み取り専用モードや細かなツール無効化による安全制御も備えています。OAuth 機能を備えた STDIO と Streamable HTTP の両トランスポートに対応しています。
Couchbase MCP Server は Python Package Index (PyPI) パッケージおよび Docker 経由で配布されています。Couchbase MCP Server のエンタープライズサポートは、Couchbase AI Data Plane のライセンスを取得することで利用できます。このライセンスには、Couchbase Agent Memory と Couchbase Agent Catalog の利用権およびエンタープライズサポートも含まれます。
ドキュメント全文: docs.couchbase.com/mcp-server
目次
- Couchbase MCP Server を選ぶ理由
- サーバーの選択
- Operational Server
- Operational Insights Server
- 共通設定
- クライアントのセットアップ
- Docker
- トラブルシューティング
- FAQ
- コントリビューション
- 利用データ、LLM のリスク、サポートポリシー
Couchbase MCP Server を選ぶ理由
- デフォルトで安全 —
CB_MCP_READ_ONLY_MODE=falseを設定しない限り、書き込みツールは読み込まれず、データを変更するクエリはブロックされます。個々のツールを無効にしたり、ユーザー確認を必須にしたりすることもできます。 - Couchbase Server と Operational Insights — Operational Server は同じ設定で Couchbase Capella またはセルフマネージドの Couchbase Server クラスターに接続し、Operational Insights Server はセルフマネージドの Operational Insights クラスターに接続します。
- RBAC を考慮 — ツール制御は LLM をガイドしますが、Couchbase ユーザーのロールベースアクセス制御が引き続き正式なセキュリティ境界となります。
- 本番環境向けトランスポート — ローカルのデスクトップクライアントには STDIO、共有デプロイにはオプションの OAuth 2.1(JWKS を公開する任意の IdP: Auth0、Okta、Keycloak、Entra、Cognito、…)、ヘルスチェック、監査ログを備えた Streamable HTTP を使用できます。Operational Server は、より多くの CPU コアを利用するために複数のワーカーを実行することもできます。
- あらゆる MCP クライアントに対応 — Claude Desktop、Cursor、Windsurf、VS Code、JetBrains AI Assistant/Junie でテスト済みです。
接続すると、次のような質問ができます。
- 「どのバケット、スコープ、コレクションがありますか。また、
ordersコレクションのスキーマは何ですか?」 - 「
status = 'active'であるusersのドキュメントのうち、最新の 10 件を検索してください。」 - 「過去 1 時間で最も遅かったクエリ 5 件は何ですか。また、カバリングインデックスが不足しているものはありますか?」
- 「このクラスターは正常ですか。また、どのサービスが稼働していますか?」
- 「次のフィールドを含む新しいドキュメントを
productsに挿入してください: …」(CB_MCP_READ_ONLY_MODE=falseが必要)
サーバーの選択
このパッケージには 2 つの MCP サーバーが含まれています。それぞれ独自のサブコマンドで起動し、異なる種類のクラスターに接続して、独自のツールを備えています。クラスターに合ったサーバーを選び、該当するセクションでセットアップとツールを確認してから、両方に共通する設定については共通設定を参照してください。両方を使う場合は、MCP クライアントにそれぞれ別のサーバーとして登録してください。
| Operational Server | Operational Insights Server | |
|---|---|---|
| 対象 | Couchbase クラスター(Capella またはセルフマネージド) | セルフマネージドの Operational Insights クラスター(Capella では利用不可) |
| サブコマンド | operational(デフォルト) | operational-insights |
| 接続文字列 | couchbase:// / couchbases:// | HTTP(S) URL、例: http://localhost:8095 |
| 認証情報の変数 | CB_CONNECTION_STRING、CB_USERNAME、… | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING、CB_OPERATIONAL_INSIGHTS_USERNAME、… |
| ツール | 52 — クラスターのヘルス、スキーマ、KV、SQL++、インデックス、全文検索とベクトル検索、クエリパフォーマンス | 13 — スキーマ、SQL++(同期および非同期)、インデックス、エクスポート |
| HTTP のデフォルトポート | 8000 | 8001 |
| ログファイルのデフォルト | mcp_server.log | mcp_server_operational_insights.log |
現在、Operational Server ではサブコマンドは省略可能です。サブコマンドなしの
couchbase-mcp-serverで起動できますが、設定を明確にするため、サブコマンドを指定することをおすすめします。オプションはサブコマンドの後に指定します:couchbase-mcp-server operational --transport=http。インストール済みのバージョンはuvx couchbase-mcp-server --versionで確認できます。
Operational Server
operational Server は、couchbase Python SDK を使用して、Capella またはセルフマネージドの Couchbase Server 上の Couchbase クラスターに接続します。
Operational Server のクイックスタート
稼働中の Couchbase クラスターと MCP クライアントが必要です。クラスターを用意するには、Capella の無料枠が最も手軽です(サンプルデータセットをインポートできます)。クライアントに次の設定のいずれか 1 つを追加してください(各クライアントでの設定場所はクライアントのセットアップを参照)。クライアントにすでに他のサーバーがある場合は、既存の mcpServers オブジェクトに couchbase を追加してください。
uvx で PyPI から実行(uv と Python 3.11 以降が必要):
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Docker で実行(Docker のみ必要):
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_CONNECTION_STRING=couchbases://connection-string",
"-e", "CB_USERNAME=username",
"-e", "CB_PASSWORD=password",
"couchbase/mcp-server:latest", "operational"
]
}
}
}
ソースから実行
git clone https://github.com/couchbase/mcp-server-couchbase.git
{
"mcpServers": {
"couchbase": {
"command": "uv",
"args": [
"--directory", "path/to/cloned/repo/mcp-server-couchbase/",
"run", "src/mcp_server.py", "operational"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
path/to/cloned/repo/mcp-server-couchbase/ はクローンしたリポジトリへのパスです。末尾のスラッシュは残してください。更新を取得した後、uv sync を実行して依存関係を更新してください。
Operational Server の接続と認証
ユーザー名とパスワード、またはクライアント証明書(mTLS)のどちらかを使用してください。両方が設定されている場合は、証明書が使用されます。
| 環境変数 | CLI 引数 | 説明 |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | クラスターへの接続文字列。必須 |
CB_USERNAME / CB_PASSWORD | --username / --password | 基本認証 |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | mTLS 認証 |
CB_CA_CERT_PATH | --ca-cert-path | 自己署名または信頼されていないサーバー証明書用のルート証明書(Capella では不要) |
mTLS の例
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
"CB_CLIENT_KEY_PATH": "/path/to/client.key"
}
}
}
}
Operational Server のツール
デフォルトで有効な読み取り専用モードでは、書き込みツール(✏️ のマーク)は読み込まれません。🖥️ のマークが付いたツールはセルフマネージド環境専用です。Capella では公開されていない管理 REST エンドポイントを使用するか、(discover_tool_input_values)そのツール用の参照データのみを提供するため、セルフマネージドの Couchbase Server 7.6 以降が必要です。また、Capella 接続では登録されません。
クラスターのセットアップとヘルス
| ツール | 説明 |
|---|---|
get_server_configuration_status | クラスターに接続せずに、読み取り専用モード、無効化または確認必須のツール、OAuth、ログ記録、監査カウンターなどのサーバー状態と設定を表示 |
test_cluster_connection | クラスターに接続して認証情報を確認 |
get_cluster_health_and_services | クラスターのヘルスと稼働中のサービスを確認。service_types で絞り込み可能 |
get_client_connectivity_report | アクティブなネットワークプローブを行わずに、SDK にキャッシュされた接続診断情報を表示 |
get_cluster_metrics 🖥️ | 過去の時間範囲におけるクラスター統計(stats-range エンドポイント) |
get_cluster_tasks 🖥️ | 現在実行中のタスク(リバランス、コンパクション、XDCR、インデックス構築)。ro_admin が必要 |
get_cluster_health_snapshot 🖥️ | ノードごとのヘルス(サービスのトポロジー、メンバーシップ、オーケストレーター、ヘルスの集計)。ro_admin が必要 |
get_bucket_config 🖥️ | 1 つまたはすべてのバケットの設定と稼働状態(クォータ、エビクション、レプリカ、耐久性、ストレージ、コンパクション)。ro_admin が必要 |
get_cluster_system_events 🖥️ | システムイベントログ(設定変更、フェイルオーバー、リバランス、再起動)。since_time で期間を指定。Full Admin または Cluster Admin が必要 |
discover_tool_input_values 🖥️ | 他のツールで必要となる正確な入力値(例: get_cluster_metrics のすべてのメトリック名)を検索。オフラインで動作 |
データモデルとスキーマの検出
| ツール | 説明 |
|---|---|
get_buckets_in_cluster | クラスター内のすべてのバケットを一覧表示 |
get_scopes_in_bucket | バケット内のすべてのスコープを一覧表示 |
get_collections_in_scope | スコープ内のすべてのコレクションを一覧表示(Query サービスが必要) |
get_scopes_and_collections_in_bucket | バケット内のすべてのスコープとコレクションを一覧表示 |
get_schema_for_collection | コレクションの構造を推定 |
create_scope ✏️ | バケットにスコープを作成(Server 7.6 以降および Capella) |
create_collection ✏️ | 既存のスコープにコレクションを作成(Server 7.6 以降および Capella) |
delete_scope ✏️ | スコープとそのすべてのコレクションを削除 — 元に戻せません |
delete_collection ✏️ | コレクションとそのすべてのドキュメントを削除 — 元に戻せません |
ドキュメント(KV)操作
| ツール | 説明 |
|---|---|
get_document_by_id | ID でドキュメントを取得 |
lookup_subdocument | ドキュメント全体を取得せずに、特定のパス、存在確認、件数を読み取り |
upsert_document_by_id ✏️ | ID でドキュメントをアップサート |
insert_document_by_id ✏️ | 新しいドキュメントを挿入(すでに存在する場合は失敗) |
replace_document_by_id ✏️ | 既存のドキュメントを置換(存在しない場合は失敗) |
delete_document_by_id ✏️ | ID でドキュメントを削除 |
mutate_subdocument ✏️ | 既存のドキュメント内のパスを変更(アップサート、挿入、置換、削除、配列操作、カウンター) |
クエリとインデックス作成
| ツール | 説明 |
|---|---|
run_sql_plus_plus_query | バケットとスコープを指定して SQL++ クエリを実行 — コレクション名を直接使用します(SELECT * FROM users)。読み取り専用モードではデータ変更ステートメントがブロックされます |
explain_sql_plus_plus_query | EXPLAIN プランを生成して評価(メタデータ、抽出されたプラン、検出事項) |
get_index_advisor_recommendations | SQL++ クエリに対する Index Advisor の推奨事項 |
list_indexes | 定義を含むインデックスを一覧表示。バケット、スコープ、コレクション、名前で絞り込み可能。ベクトルインデックスにフラグを付与(is_vector、vector_type) |
get_index_stats 🖥️ | ノードごとのインデックスサイズ、断片化、スキャントラフィック、遅延を表示し、負荷や未使用のインデックスを検出 |
create_query_index ✏️ | スカラー、Hyperscale ベクトル、または Composite ベクトルの GSI インデックスを作成(index_type)。デフォルトでは遅延作成されるため、続けて build_index を実行 |
create_index ✏️ | 非推奨 — create_query_index を使用してください。2.0 で削除 |
build_index ✏️ | コレクション上の遅延インデックスをすべて構築 |
drop_index ✏️ | GSI インデックス(スカラーまたはベクトル)を削除 |
全文検索(FTS)
Couchbase Server 7.6 以降と Search サービスが必要です。スコープレベルとクラスター全体(レガシー)の両方のインデックスに対応しています。スコープレベルの場合は bucket_name と scope_name を両方指定し、クラスター全体の場合はどちらも省略してください。
| ツール | 説明 |
|---|---|
list_search_indexes | Search インデックスを一覧表示 — クラスター単位、バケット単位、またはスコープ単位 |
get_search_index_definition | 1 つの Search インデックスの完全な定義(マッピング、アナライザー、プランパラメーター) |
run_search | 生の JSON 本文からベクトル以外の FTS クエリを実行します。explain=true は実行プランを返します |
upsert_search_index ✏️ | ベクトルフィールドのマッピングを含む Search インデックスを作成または更新します。更新すると全体が再構築されます — 同時変更を上書きしないよう、現在の uuid を渡してください |
drop_search_index ✏️ | Search インデックスを削除 — 元に戻せません |
ベクトル検索
どちらのツールも、Embedding Providers で設定されたモデルを使って、プレーンなクエリテキストを埋め込みます。セルフマネージドの Couchbase Server と Capella で利用できます。
| ツール | 説明 |
|---|---|
run_vector_query | APPROX_VECTOR_DISTANCE() 経由で GSI ベクトルインデックス(Server 8.0 以降)に対して類似性検索を実行します。インデックスは自動的に選択されます。SQL++ の where プレフィルターと Hyperscale チューニング(num_probes、rerank、top_n_scan)をサポートします。ドキュメント全体を返します |
run_vector_search | 名前付きインデックスに対して Search Service のベクトル検索(Server 7.6 以降)を実行します。scalar_query を指定するとハイブリッド検索になり、prefilter で候補を先に絞り込みます。各ヒットについて、インデックスに保存されたフィールドを返します |
クエリパフォーマンス分析
| ツール | 説明 |
|---|---|
get_longest_running_queries | 平均サービス時間が最も長いクエリ |
get_most_frequent_queries | 実行頻度が最も高いクエリ |
get_queries_with_largest_response_sizes | 応答サイズが最も大きいクエリ |
get_queries_with_large_result_count | 結果数が最も多いクエリ |
get_queries_using_primary_index | プライマリーインデックスを使用するクエリ |
get_queries_not_using_covering_index | カバリングインデックスを使用しないクエリ |
get_queries_not_selective | セカンダリーインデックス、プライマリーインデックス、またはシーケンシャルスキャンが最終結果よりはるかに多くのドキュメントを返すクエリ |
Query Service の健全性 🖥️
これらは、各クエリノードで Query Service 独自の管理 REST API を呼び出します。
| ツール | 説明 |
|---|---|
get_cluster_query_vitals | クエリエンジンの健全性:リクエストレート、アクティブ/キュー内のリクエスト、メモリ、GC、稼働時間。ro_admin が必要です |
get_active_queries | 現在、すべてのクエリノードで実行中のクエリ。ro_admin が必要です |
delete_active_query ✏️ | リクエスト ID を指定して実行中のクエリをキャンセルします。Full Admin または Cluster Admin が必要です |
Capella で自動的に無効になるツール
🖥️ ツールは、Capella が公開していない管理 REST エンドポイントを通じて Couchbase にアクセスします(例外の discover_tool_input_values は、それらを必要とするツールにのみ使われるため、利用できません)。CB_CONNECTION_STRING 内のすべてのホストが .cloud.couchbase.com で終わる場合、サーバーはこれらのツールを登録せず、get_server_configuration_status と起動ログに、独自の無効なツールと併せて表示します。get_cluster_health_and_services や get_client_connectivity_report などの SDK ベースのツールは引き続き利用できます。
| ツール | 必要なエンドポイント |
|---|---|
get_cluster_metrics | Management REST(/pools/default/stats/range) |
get_cluster_tasks | Management REST(/pools/default/tasks) |
get_bucket_config | Management REST(/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | Management REST、およびノードごとのエンドポイント |
get_cluster_system_events | Management REST(/events) |
get_index_stats | Index Service REST(各インデクサーの /api/v1/stats) |
get_cluster_query_vitals | Query Service REST(/admin/vitals) |
get_active_queries | Query Service REST(/admin/active_requests) |
delete_active_query | Query Service REST(DELETE /admin/active_requests/{id}) |
discover_tool_input_values | なし(オフラインで動作)ですが、get_cluster_metrics にのみ使われます。Capella にはありません |
Embedding Providers
run_vector_query と run_vector_search は、CB_MCP_EMBEDDING_MODEL_PROVIDER で設定されたプロバイダーを使ってクエリテキストを埋め込みます。これは任意です。設定しなくてもサーバーは通常どおり起動し、両方のツールが登録されますが、呼び出すと設定すべき項目を説明するエラーが返されます。
CB_MCP_EMBEDDING_MODEL_PROVIDER | 必須 | 任意 | 備考 |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL、CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service。CB_MCP_EMBEDDING_MODEL_ENDPOINT は、Capella の AI Data Plane > Models で確認できる、デプロイメント固有の URL です(例:https://<id>.ai.couchbase.com) |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | エンドポイントを設定すると、OpenAI 互換のローカルサーバー(Ollama、vLLM、LM Studio)を使用できます |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID、CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY、CB_MCP_EMBEDDING_MODEL_AWS_REGION | Amazon Titan 埋め込みモデル(例:amazon.titan-embed-text-v2:0)。このプロバイダーは Titan の inputText リクエスト形式を送信するため、Cohere Embed など、その他の Bedrock 埋め込みモデルはまだサポートされていません。認証情報を省略すると、デフォルトの AWS チェーンが使用されます。追加で必要なもの:pip install couchbase-mcp-server[bedrock-embeddings] |
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
"CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
"CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}
すべてのオプション
operational server
のすべての環境変数と CLI フラグ
Operational Insights server は同じオプションを受け付けますが、独自の接続設定を持ち、CB_MCP_EMBEDDING_MODEL_* オプションはありません。
| 環境変数 | CLI 引数 | 説明 | デフォルト |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | Couchbase クラスターへの接続文字列 | 必須 |
CB_USERNAME | --username | 基本認証に必要なバケットへのアクセス権を持つユーザー名 | 必須(または mTLS 用のクライアント証明書とキーが必要) |
CB_PASSWORD | --password | 基本認証用のパスワード | 必須(または mTLS 用のクライアント証明書とキーが必要) |
CB_CLIENT_CERT_PATH | --client-cert-path | mTLS 認証用のクライアント証明書ファイルのパス | mTLS を使用する場合は必須(またはユーザー名とパスワードが必要) |
CB_CLIENT_KEY_PATH | --client-key-path | mTLS 認証用のクライアントキーファイルのパス | mTLS を使用する場合は必須(またはユーザー名とパスワードが必要) |
CB_CA_CERT_PATH | --ca-cert-path | サーバーが自己署名証明書または信頼されていない証明書を使用するよう設定されている場合の、TLS 用サーバールート証明書のパス。Capella に接続する場合は不要です | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | すべてのデータ変更(KV、Query、スコープ/コレクション管理、インデックス管理、FTS インデックス管理)を禁止します。有効にすると、書き込みツールは読み込まれません。 | true |
CB_MCP_TRANSPORT | --transport | トランスポートモード:stdio、http | stdio |
CB_MCP_HOST | --host | HTTP トランスポートモードのホスト | 127.0.0.1 |
CB_MCP_PORT | --port | HTTP トランスポートモードのポート | 8000 |
CB_MCP_WORKERS | --workers | http トランスポートのサーバーワーカープロセス数。1 を超える値を指定すると、ステートレス HTTP モードで実行されます(複数ワーカーを参照) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | 各 HTTP リクエストをセッションごとの状態なしで処理します。http の場合にのみ有効です。確認が必要なツールとは併用できません(複数ワーカーを参照) | ワーカー数が 1 より大きい場合は true、それ以外は false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | 無効にするツール(ツールの無効化を参照) | なし |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | MCP elicitation を通じて実行前にユーザーの明示的な確認が必要なツール(確認の要求を参照) | なし |
CB_MCP_LOG_LEVEL | --log-level | MCP サーバーのログレベル:off、debug、info、warning、error(ログ記録を参照) | info |
CB_MCP_LOG_SINKS | --log-sinks | カンマ区切りのログ出力先:stderr、file、または両方(ログ記録を参照) | stderr |
CB_MCP_LOG_FILE | --log-file | レベル別ログファイルのベースパス(file シンクが有効な場合のみ使用) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | ローテーション前のログファイルごとのグローバル最大サイズ(MB 単位)。個別に上書きされない限り、すべてのレベルに適用されます。0、または負の値、nan、inf など使用できない値は無効であり、起動時の警告とともにデフォルト値に戻ります | 1(1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | 非推奨 — CB_MCP_LOG_ROTATION_MAX_SIZE_MB(MB 単位)を使用してください。後方互換性のため引き続き有効な、グローバルなローテーションサイズ(バイト単位)。CB_MCP_LOG_ROTATION_MAX_SIZE_MB も設定されている場合は無視されます | 未設定 |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | ERROR ログファイルのローテーションサイズ(MB 単位)。ERROR に対する CB_MCP_LOG_ROTATION_MAX_SIZE_MB を上書きします | CB_MCP_LOG_ROTATION_MAX_SIZE_MB を継承 |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | WARNING ログファイルのローテーションサイズ(MB 単位)。WARNING に対する CB_MCP_LOG_ROTATION_MAX_SIZE_MB を上書きします | CB_MCP_LOG_ROTATION_MAX_SIZE_MB を継承 |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | INFO ログファイルのローテーションサイズ(MB 単位)。INFO に対する CB_MCP_LOG_ROTATION_MAX_SIZE_MB を上書きします | CB_MCP_LOG_ROTATION_MAX_SIZE_MB を継承 |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | DEBUG ログファイルのローテーションサイズ(MB 単位)。DEBUG に対する CB_MCP_LOG_ROTATION_MAX_SIZE_MB を上書きします | CB_MCP_LOG_ROTATION_MAX_SIZE_MB を継承 |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | レベル別ログファイルごとに保持するローテーション済みバックアップファイル数(現行ファイルを除く)。個別に上書きされない限り、すべてのレベルに適用されます。0 の場合は現行ファイルのみを保持します(ログ記録を参照) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | ERROR ログファイルで保持するローテーション済みバックアップ数。ERROR に対するグローバル数を上書きします | CB_MCP_LOG_RETENTION_BACKUP_COUNT を継承 |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | WARNING ログファイルで保持するローテーション済みバックアップ数。WARNING に対するグローバル数を上書きします | CB_MCP_LOG_RETENTION_BACKUP_COUNT を継承 |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | INFO ログファイルで保持するローテーション済みバックアップ数。INFO に対するグローバル数を上書きします | CB_MCP_LOG_RETENTION_BACKUP_COUNT を継承 |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | DEBUG ログファイルで保持するローテーション済みバックアップ数。DEBUG に対するグローバル数を上書きします | CB_MCP_LOG_RETENTION_BACKUP_COUNT を継承 |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | ベアラー JWT の検証に使用する ID プロバイダーの JWKS エンドポイント。issuer と audience を設定すると OAuth が有効になります(OAuth 2.1 認可を参照) | なし |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | 期待される JWT iss クレーム。OAuth を有効にするには必須です | なし |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | 期待される JWT aud クレーム。OAuth を有効にするには必須です | なし |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | JWT 署名アルゴリズム:RS256/384/512、ES256/384/512、PS256/384/512 のいずれか | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | このサーバーの公開ベース URL。設定すると、RFC 9728 Protected Resource Metadata を公開し、PRM 対応クライアントが IdP を検出できるようにします | なし |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | 「read」アクセスとして扱う OAuth スコープラベルを上書きします(PRM で公開され、トークンの scope/scp クレームと照合されます)。IdP が標準形式を出力できない場合に使用します | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | 「write」アクセスとして扱う OAuth スコープラベルを上書きします。意味は read ラベルと同じです | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | 監査ログを有効にします。CB_MCP_LOG_* 運用ログとは別のシンクで、安定したスキーマと独自の保持設定を使用します(監査を参照) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | カンマ区切りの監査出力先:console、file、または両方。console は stderr に書き込みます。stdio では JSON-RPC プロトコルが流れるため、stdout には書き込みません | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | 監査ログファイルのパス。file がシンクに含まれる場合は必須です。拡張子の前にホスト名とプロセス ID が挿入されます(audit.log → audit.<host>.<pid>.log) | なし |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | ローテーション前に現行の監査ファイルが到達できる最大サイズ(MB 単位)。0 はサイズベースのローテーションを無効にします | 10(10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | ローテーション前に現行の監査ファイルが到達できる経過時間。<value><unit> 形式で指定し、単位は d(24 時間)または w(7 日)です。例:1d、30d、8w。0 は間隔ベースのローテーションを無効にします | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | 監査ファイルごとに保持するローテーション済みバックアップ数(現行ファイルを除く)。バックアップは gzip 圧縮されます。0 の場合、バックアップは保持されません。これは単一ファイルのサイズを制限するものであり、ディレクトリ全体ではありません。監査を参照してください | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | ツールの引数値を監査ログに記録します。デフォルトでは無効です。このリリースでは秘匿化されないため、有効にするとドキュメント本文全体を含む引数がそのまま記録されます | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | 抑制する監査イベント:カンマ区切りの数値イベント ID(例:61490,61492)、または 1 行に 1 つの ID を記載したファイル。フィルター可能なイベントのみ抑制できます | なし |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | run_vector_query / run_vector_search 用の埋め込みプロバイダー:capella、openai、cohere、voyage、bedrock のいずれか。未設定の場合、構成されるまで両ツールの埋め込み処理は無効になります。埋め込みプロバイダーの構成を参照してください | なし |
CB_MCP_EMBEDDING_MODEL | --embedding-model | 構成済み埋め込みプロバイダーのモデル名/ID | なし |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | 構成済みプロバイダーの API キー。bedrock では使用されません(代わりに AWS 認証情報チェーン/CB_MCP_EMBEDDING_MODEL_AWS_* を使用) | なし |
CB_MCP_EMBEDDING_MODEL_ENDPOINT | --embedding-model-endpoint | ベース URL の上書き(OpenAI 互換のローカルサーバー、または Capella Model Service デプロイ固有の URL。CB_MCP_EMBEDDING_MODEL_PROVIDER=capella の場合は必須) | なし |
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID | --embedding-model-aws-access-key-id | AWS アクセスキー ID。bedrock プロバイダー専用です。省略するとデフォルトの AWS 認証情報チェーンが使用されます | なし |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | AWS シークレットアクセスキー。bedrock プロバイダー専用です | なし |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | AWS リージョン。bedrock プロバイダー専用です。未設定の場合は AWS SDK 独自のリージョン解決にフォールバックします | なし |
Operational Insights Server
operational-insights サーバーは、セルフマネージドの Operational Insights クラスターに接続します。Operational Insights は、リアルタイムアプリと運用インテリジェンス向けのリアルタイム分析データベース(RT-OLAP)です。このサーバーは Capella では利用できません。couchbase-operational-insights SDK を使用します。運用サーバーとは別の独立したプロセスとして実行されます。
[!IMPORTANT]
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRINGはcouchbase://接続文字列ではなく、HTTP(S) URL です。例:http://localhost:8095、または TLS 経由のhttps://<host>:18095。これは最もよくある設定ミスです。
Operational Insights Quick Start
PyPI から uvx を使用する場合:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational-insights"],
"env": {
"CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
"CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
"CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
}
}
}
}
Docker を使用する場合:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
"-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
"-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
"couchbase/mcp-server:latest", "operational-insights"
]
}
}
}
ソースから実行する場合は、運用サーバーのソース構成を使用し、最後の引数として operational-insights を指定し、上記の変数を設定してください。
Operational Insights Connection and Authentication
| 環境変数 | CLI 引数 | 説明 |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | エンドポイント URL(HTTP/HTTPS)。必須 |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | ユーザー名 |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | パスワード |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | 自己署名または信頼されていないサーバー証明書用のルート証明書(PEM) |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | mTLS 用クライアント証明書 — PEM(鍵を含む)または PKCS#12 バンドル(.p12/.pfx、鍵なし)。https:// URL が必要です。ユーザー名/パスワードより優先されます |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | クライアント証明書用の秘密鍵(PEM)。PKCS#12 の場合は未設定のままにします |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | 暗号化された鍵または PKCS#12 バンドルのパスワード |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | クエリ結果の最大サイズ(バイト単位)。未設定の場合、制限はありません。設定すると、上限に達した時点で読み取りが停止し、応答に truncated: true が報告されます。上限を超える行は返されません。4 MiB(4194304)を超える値は 4 MiB に制限され、起動時に stderr に警告が出力されます |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | 各非同期クエリリクエストのタイムアウト(秒単位):クエリの開始、ステータスの確認、結果の取得、破棄、キャンセルに適用されます。取得時はダウンロード全体に適用されるため、読み取りにこれ以上かかる結果は失敗します。大きな結果や低速な接続では値を大きくしてください。正の整数。既定値は 30、最大値は 600 です。これより大きい値は 600 に制限され、警告が出力されます。それ以外の無効な値は警告として記録され、30 が使用されます |
共通設定はすべて適用されますが、運用サーバーとは次の点が異なります。
- 既定のポートは
8001、既定のログファイルはmcp_server_operational_insights.logです。そのため、両方のサーバーを同時に実行できます。 - 非同期クエリハンドルはプロセスメモリに保存されるため、サポートされるワーカーは 1 つのみです(
CB_MCP_WORKERS=1)。 CB_MCP_EMBEDDING_MODEL_*オプションはありません。
Operational Insights ツール
get_server_configuration_status を除くすべての名前には operational_insights_ が接頭辞として付きます。そのため、1 つのクライアントに両方のサーバーを名前の衝突なく登録できます。書き込みツール(✏️ マーク付き)は、既定で有効な読み取り専用モード中は読み込まれません。
サーバーのステータス
| ツール | 説明 |
|---|---|
get_server_configuration_status | 運用サーバーと同じツール |
データモデルとスキーマの検出
| ツール | 説明 |
|---|---|
operational_insights_get_databases_in_cluster | データベースを一覧表示 |
operational_insights_get_scopes_in_database | データベース内のスコープを一覧表示 |
operational_insights_get_collections_in_scope | スコープ内のコレクション(データセット)を一覧表示 |
operational_insights_get_schema_for_collection | サンプリングによってコレクションの JSON スキーマを推定 |
クエリとインデックス
| ツール | 説明 |
|---|---|
operational_insights_list_indexes | System.Metadata.Index のセカンダリインデックスを一覧表示 |
operational_insights_explain_query | SQL++ ステートメントを実行せずに EXPLAIN |
operational_insights_run_query_sync | SQL++ を実行し、結果サイズの上限まで行を返します。代わりにエクスポートも可能です。読み取り専用モードはサーバー側で適用されます |
operational_insights_run_query_async | 長時間実行されるクエリを開始し、行を待たずに query_handle を返します。大規模なエクスポートにも推奨されます。読み取り専用モードはサーバー側で適用されます |
operational_insights_get_async_query_results | 非同期クエリをポーリングします。準備ができると行(またはエクスポート先)を返します |
operational_insights_discard_async_query_results | 完了した非同期クエリの結果を解放 |
operational_insights_cancel_async_query | 実行中の非同期クエリを停止(読み取り専用モードでも許可) |
operational_insights_create_index ✏️ | CREATE INDEX を使用してセカンダリインデックスを作成 |
非同期クエリは、開始 → ポーリング → 破棄またはキャンセルの流れで処理します。operational_insights_run_query_async は query_handle を返し、operational_insights_get_async_query_results を準備ができるまでポーリングします。その後、operational_insights_discard_async_query_results で結果を解放するか、実行中のクエリを operational_insights_cancel_async_query で停止します。
大規模な結果のエクスポート
行を返す代わりに、operational_insights_run_query_sync と operational_insights_run_query_async はステートメントを COPY ... TO でラップし、行を外部オブジェクトストレージに書き込めます。copy_to_link(CREATE LINK ... TYPE S3 で作成した既存のリンク)、copy_to_bucket、copy_to_path の 3 つすべてと、任意で copy_to_format(既定値の json または parquet)を渡します。ツールは行を含まない確認応答を返します。
{
"success": true,
"exported": true,
"destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
"message": "Results were written to my-exports/exports/run1 as json. ..."
}
- 宛先の指定が不完全な場合、行を黙って返すのではなく拒否されます。
- 同期ツールはアップロード全体の完了を待ちます。大規模なエクスポートには非同期ツールを推奨します。
- エクスポートは外部ストレージに書き込むため、読み取り専用モードではブロックされます。そのため、
CB_MCP_READ_ONLY_MODE=falseまたはcouchbase-mcp:writeを持つトークンが必要です。 csvは、任意のSELECTから推定できない明示的な出力スキーマが必要なため、提供されません。
共通設定
これらの設定は両方のサーバーで同じように機能します。各オプションは環境変数、またはサブコマンドの後に指定する CLI フラグで設定できます。
安全制御
次のセキュリティ原則に従ってください。
- データベースユーザーには最小限の権限を付与する — RBAC が正式な境界です(下記参照)。
- エージェントに必要なツールだけを提供し、それ以外は無効にする — 読み込まれたツールはすべて LLM が呼び出せます。読み取り専用モードと
CB_MCP_DISABLED_TOOLSを使い、ツール一覧を必要最小限にしてください。 - 保持する機密性の高いツールには確認を必須にする — 確認の必須化を参照してください。
以下の制御は、広範なものから限定的なものへと 3 つの層を形成します。併用してください。ただし、いずれも RBAC の代わりにはなりません。
[!IMPORTANT] データベースユーザーの RBAC 権限が、正式なセキュリティ制御です。たとえば、
upsert_document_by_idとdelete_document_by_idを無効にしても、run_sql_plus_plus_queryによるINSERT/UPDATE/DELETE/MERGEの実行は阻止されません。阻止できるのは読み取り専用モード、または RBAC 権限の不足だけです。サーバーのデータベースユーザーには、必要な権限のみを付与してください。
読み取り専用モード
CB_MCP_READ_ONLY_MODE(既定値は true)は、書き込みを制御する単一のスイッチです。
true— 各サーバーのツール一覧で ✏️ マークが付いた書き込みツールは読み込まれず、データや構造を変更するクエリはブロックされます。false— 書き込みツールが読み込まれ、変更クエリが許可されます。
ツールの無効化
CB_MCP_DISABLED_TOOLS はツールを検出対象から完全に除外します。カンマ区切りのリスト、またはツール名を 1 行に 1 つずつ記載したファイルへのパスを指定できます(# はコメントの開始を示します)。
CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt
# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendations
Capella では、運用サーバーが一部の管理ツールも自動的に無効化します。
確認の必須化(elicitation)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS は、MCP の elicitation を使用して、指定したツールの実行前にユーザーへ確認を求めます。無効化するツールと同じカンマ区切り形式またはファイル形式を使用します。
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
- クライアントが elicitation をサポートしている場合、ツールの実行前にユーザーへ確認を求めます。
- サポートしていない場合は、後方互換性のため、確認なしでツールが実行されます。
- 確認には MCP セッションが必要なため、ステートレス HTTP(
CB_MCP_STATELESS_HTTP=true、または 1 を超えるCB_MCP_WORKERS)とは併用できません。この組み合わせではサーバーは起動を拒否します。ロードバランサーの背後では、確認にスティッキーセッションが必要です。ロードバランサーを参照してください。
トランスポート
| トランスポート | 用途 | エンドポイント |
|---|---|---|
stdio(既定) | サーバーをサブプロセスとして起動する単一のローカルクライアント | — |
http | 1 つのサーバーを共有する複数のクライアント。OAuth、ヘルスチェック、運用サーバーのワーカーをサポート | http://<host>:<port>/mcp |
CB_MCP_TRANSPORT でトランスポートを、CB_MCP_HOST でバインドアドレス(既定値は 127.0.0.1)を、CB_MCP_PORT でポート(未設定の場合は各サーバーの既定ポート)を設定します。OAuthを使用しない場合、HTTP エンドポイントは認証されません。
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http
次に、クライアントの接続先として URL を指定します。
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
複数のワーカー
1 つのプロセスが使用する CPU コアは最大でおよそ 1 つです。--workers N(CB_MCP_WORKERS)は、同じホストとポートの背後で N 個のプロセスを実行します。利用可能なコア数を開始点の目安にしてください。ワーカーをサポートするのは運用サーバーのみです。ワーカーが複数の場合:
httpトランスポートが必須で、クライアントのリクエストが異なるワーカーに届く可能性があるため、サーバーはステートレス HTTP モードで実行されます。たとえば、スティッキーセッションのないロードバランサーの背後にある単一ワーカーでも、--stateless-http=trueを設定できます。- 確認が必要なツールは使用できません。
- 各プロセスは、ホスト名とプロセス ID を含む名前(
mcp_server.<host>.<pid>.info.log)で独自のログファイルを書き込みます。スーパーバイザー用に 1 セット、各ワーカー用に 1 セット作成されます。
ロードバランサー
複数のサーバーインスタンスをロードバランサーの背後で実行できます。各インスタンスは独自のメモリに MCP セッションを保持するため、ロードバランサーの設定によって利用できる機能が決まります。
| ロードバランサー | サーバー設定 | 確認が必要なツール |
|---|---|---|
Mcp-Session-Id リクエストヘッダーに基づくスティッキーセッション | ワーカー 1 つ、ステートフル(既定) | サポート |
| スティッキーセッションなし | --stateless-http=true | サポートされません — 設定されている場合、サーバーは起動を拒否します |
- スティッキーセッションがない場合、ステートフルなインスタンスは、別のインスタンスで作成されたセッションのリクエストをすべて拒否します。その場合はステートレスモードを使用してください。
- Cookie ではなく、
Mcp-Session-Idヘッダーに基づいてルーティングしてください。多くの MCP クライアントは Cookie を保持しません。 - インスタンスが再起動またはフェイルオーバーすると、そのセッションと保留中の確認プロンプトは失われます。クライアントは新しいセッションを開始する必要があります。
- Operational Insights の非同期クエリは、ステートレスモードでも、クエリを開始したインスタンスのメモリに
query_handleを保持します。別のインスタンスでクエリをポーリング、破棄、またはキャンセルすると、Unknown query_handleが返されます。これらのツールは単一インスタンスで使用するか、すべての呼び出しがクエリを開始したインスタンスに届くようスティッキーセッションを使用してください。ステートレスモードではMcp-Session-Idが送信されないため、クライアント IP アドレスなど、別のアフィニティキーが必要です。
ヘルスチェック
HTTP モードでは、GET /health は MCP ポートで {"status": "ok", "server": "<server>"} を返します。これは稼働確認用のチェックです。クラスターには接続しないため(クラスターの停止によって正常なコンテナが再起動されることはありません)、OAuth が有効でも認証は不要で、すべてのワーカーが応答します。プローブの例はDockerを参照してください。
OAuth 2.1 認可
--transport=http を使用すると、どちらのサーバーもOAuth 2.1 リソースサーバーとして動作し、ID プロバイダーの JWKS に照らしてベアラー JWT を検証できます。JWKS を公開する任意の OAuth 2.1/OIDC プロバイダーで動作し、トークンの発行やユーザー管理は行いません。stdio では 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 も公開されます。- アクセスは、トークンの
scope/scpクレームに含まれる 2 つのスコープで制御されます。couchbase-mcp:read(読み取りツール)とcouchbase-mcp:write(書き込みツール)です。完全なアクセスには両方が必要です。IdP がこれらのラベルを出力できない場合は、CB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELで名前を変更してください。両方のサーバーで同じラベルを使用するため、1 つの IdP 設定で両方をカバーできます。
uvx couchbase-mcp-server operational \
--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>'
IdP の設定については、運用サーバーと Operational Insights サーバーの OAuth ドキュメントを参照してください。
ログ記録
各サーバーは、既定で info レベルのログを stderr に記録します。
CB_MCP_LOG_LEVEL—off、error、warning、info(ライフサイクルイベントとツール呼び出し)、またはdebug。CB_MCP_LOG_SINKS—stderr、file、または両方。fileを指定すると、レベルごとに1つのローテーションファイルがCB_MCP_LOG_FILEの隣に書き込まれます(mcp_server.info.log、mcp_server.error.log、…)。- ローテーションと保持 —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(デフォルト1 MB)とCB_MCP_LOG_RETENTION_BACKUP_COUNT(デフォルト1)はすべてのレベルに適用されます。CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNTでレベルごとに上書きできます。無効なサイズはデフォルトにフォールバックし、起動時に警告が表示されます。CB_MCP_LOG_MAX_BYTESは非推奨です。 - 設定スナップショット —
fileシンクを使用すると、環境と秘匿化されたサーバー設定のJSONレコードが、サポート用に起動のたびにmcp_server_config.log.jsonへ書き込まれます。
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file
通常、MCPクライアントもサーバーのstderrを取得します。場所についてはクライアントの設定を参照してください。詳細は、運用サーバーおよびOperational Insightsサーバーのログ記録ドキュメントを参照してください。
監査
監査ログには誰が何を行い、それが許可されたかどうかが記録されます。何が問題だったかを記録する運用ログとは別のものです。エージェントについてこれに答えられるのはMCPサーバーだけです。すべてのリクエストは単一のデータベースユーザーとしてクラスターに到達し、スコープ拒否、読み取り専用によるブロック、確認の拒否といった判断は、そもそもクラスターに到達しないためです。
監査はデフォルトで無効です。CB_MCP_AUDIT_LOG_ENABLED=trueで有効にすると、CB_MCP_AUDIT_LOG_SINKS=fileとCB_MCP_AUDIT_LOG_FILE_PATHを設定しない限りstderrに書き込まれます。
# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
--audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
--audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
--audit-log-retention-max-backups=90
レコードは、Couchbase ServerおよびSync Gatewayと同じフィールド用語を使ったJSON Lines形式です。
{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}
監査の動作
- ID —
real_useridは呼び出し元です。oauth(トークンのサブジェクト)、local(stdioの場合はOSユーザー)、またはanonymous(OAuthを使わないHTTPの場合。起動時に警告が表示されます)。 - 相関 —
cidは1つのリクエストからのすべてのレコードをグループ化し、SQL++のclient_context_idとして送信されるため、Couchbase ServerのclientContextIdと正確に結合できます。意図的にセッション識別子はありません。 - イベント — 固定の番号付きカタログ(ライフサイクル、初期化、トークン拒否、スコープ拒否、読み取り専用によるブロック、確認の拒否/スキップ、およびツールカテゴリごとの読み取り/書き込みのペア)。
queryとsearchは例外です。ステートメント駆動型および検索のサーフェスでは区別を確実に行えないため、それぞれ読み取り/書き込みのペアではなく単一のイベントとして記録されます。ベクトル操作はこの2つのカテゴリに含まれます。完全なカタログはパッケージ内のdescriptor.jsonとして提供されます。運用サーバーはブロック0xF000(61440)、Operational Insightsは0x10000(65536)を使用し、どちらもコアイベントには0xE000(57344)を共有します。 - フィルタリング —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSは数値IDで読み取りイベントを抑制します(例:61490,61492)。書き込みイベントとセキュリティイベントは無効にできません。また、単一イベントのカテゴリであるquery(61507、Operational Insightsでは65603)とsearch(61510)も無効にできません。各カテゴリの書き込みと読み取りの両方を1つのイベントで扱うため、無効にすると変更の記録が失われます。 - ローテーション — サイズ(
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB、デフォルト10)と経過時間(CB_MCP_AUDIT_LOG_ROTATION_INTERVAL、デフォルト1d)のうち、先に到達した方でローテーションします。0を指定すると、どちらも無効になります。ローテーションされたファイルにはタイムスタンプが付与され、gzip圧縮されます。稼働中のファイルはtail -f用にプレーンテキストのままです。 - プロセスごとのファイル — ファイル名にホスト名とpidが挿入されます(
audit.log→audit.<host>.<pid>.log)。そのため、複数のプロセスが同じファイルを共有することはありません。 - 保持はファイルごと —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(デフォルト10)で、1つのファイルのバックアップ数を制限します。新しいプロセスは起動のたびに新しいファイルを書き込み、古いファイルは削除されないため、ボリュームの容量を確保するか、古いaudit.*.log*ファイルを定期的に削除してください。 - フェイルオープン — ファイルに書き込めない場合もサーバーはサービスを継続し、破棄されたレコード数をカウントします。
get_server_configuration_statusはwritten/dropped/write_errorsを報告します。 - ツール引数 —
CB_MCP_AUDIT_LOG_TOOL_ARGS=trueを指定した場合にのみ記録され、起動時に警告が表示されます。このリリースでは秘匿化されないため、ドキュメント本文全体を含む引数がそのまま書き込まれます。
クライアントの設定
各クライアントには、運用サーバーまたはOperational Insightsのクイックスタートにあるサーバー設定を、それぞれの設定場所に追加する必要があります。以下の例では運用サーバーを使用します。
Claude Desktop
- 設定ファイルを開きます(MCPクイックスタートガイドを参照)。
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
mcpServersの下にサーバーを追加し、Claude Desktopを再起動します。
ログ: macOSでは~/Library/Logs/Claude、Windowsでは%APPDATA%\Claude\Logs。詳細はMCPトラブルシューティングガイドを参照してください。
Cursor
- Cursor Settings > Tools & Integrations > MCP Toolsに移動します(CursorのMCPドキュメントを参照)。または、ワンクリックのCursorにインストールリンクを使い、プレースホルダーの接続文字列と認証情報を置き換えます。
mcpServersの下に設定を追加して保存します。- MCPサーバーの一覧を更新し、
couchbaseが有効になっていることを確認します。
ログ: 下部パネルでOutputを開き、Cursor MCPを選択します。
Windsurf Editor
- Command Palette > Windsurf MCP Configuration Panel、またはWindsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Serversを開きます(WindsurfのMCPドキュメントを参照)。
- Add Server > Add custom serverをクリックし、設定を貼り付けて保存します。
- サーバーの一覧を更新し、
couchbaseが有効になっていることを確認します。
VS Code
VS Codeでは、トップレベルキーとしてmcpServersではなくserversを使用します。ワークスペースの場合は.vscode/mcp.jsonに設定を記述するか、すべてのワークスペースに適用するにはMCP: Open User Configurationを実行します(VS CodeのMCPドキュメントを参照)。
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
ファイルを保存するとサーバーが起動します。サーバーを管理するには、その上にあるRunning | Stop | n Toolsアクションを使用します。
ログ: MCP: List Serversを実行し、couchbaseを選択してからShow Outputを選択します。
JetBrains IDE
- AI AssistantまたはJunieプラグインをインストールします。
- Settings > Tools > AI Assistant (or Junie) > MCP Serverに移動し、**+**をクリックして設定を追加し、Applyをクリックします。
- サーバーのステータスにカーソルを合わせると、ツールが表示されます。
ログ: Help > Show Log in Finder (Explorer) > mcp > couchbase。
Docker
ビルド済みイメージはDocker Hubでcouchbase/mcp-serverとして公開されており、サーバーはDocker MCP Catalogにも掲載されています。上記と同じ環境変数を使ってコンテナを設定してください。タグ、ボリューム、ヘルスチェックの例については、Docker Hubページ(DOCKER.md)を参照してください。
HTTPで実行する場合、コンテナ外部からアクセスできるように、サーバーを0.0.0.0にバインドする必要があります。
docker run --rm \
-e CB_CONNECTION_STRING='<couchbase_connection_string>' \
-e CB_USERNAME='<database_user>' \
-e CB_PASSWORD='<database_password>' \
-e CB_MCP_TRANSPORT=http \
-e CB_MCP_HOST=0.0.0.0 \
-p 8000:8000 \
couchbase/mcp-server:latest operational
- Couchbaseがホストマシン上で動作している場合は、接続文字列に
couchbase://host.docker.internalを使用します(Dockerネットワークを参照)。別のコンテナのネットワークに参加するには--network=<your_network>を使用します。 - Operational Insightsサーバーを実行するには、
operationalの代わりにoperational-insightsを追加します(ポート8001)。
ソースからイメージをビルドする
docker build -t mcp/couchbase-src .
./build.sh [image-name]はCIと同じ引数でビルドします。GIT_COMMIT_HASHとBUILD_DATEのビルド引数を設定し、イメージにlatestと<short-commit>のタグを付けます(デフォルト名は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 .
# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest
トラブルシューティング
詳しいガイドについては、運用サーバーおよびOperational Insightsサーバーのトラブルシューティングドキュメントと、運用サーバーおよびOperational Insightsサーバーのセキュリティガイドラインを参照してください。簡単な確認項目は次のとおりです。
- 接続文字列、ユーザー名/パスワード、または証明書のパスを確認します。
- Capellaの場合、サーバーを実行しているマシンからクラスターへの接続が許可されていることを確認します。
- データベースユーザーが少なくとも1つのバケットにアクセスできることを確認します。
- クライアントが
uv/uvxを見つけられない場合は、commandに絶対パスを指定します。 - ソースから実行している場合は、設定内のリポジトリパスを確認し、更新を取得した後に
uv syncを実行します。 get_server_configuration_statusを呼び出して、サーバーが実際に解決した設定を確認し、クライアントのログも確認します(クライアントの設定を参照)。
FAQ
Claude DesktopをCouchbaseに接続するにはどうすればよいですか? クイックスタートの設定をclaude_desktop_config.jsonに追加して、Claude Desktopを再起動します。クライアントの設定を参照してください。
Couchbase Capellaで使用できますか? はい、運用サーバーで使用できます。同じ設定がCapellaとセルフマネージドクラスターの両方で機能しますが、一部の管理ツールはセルフマネージドクラスターでのみ利用できます(ツールを参照)。Operational Insightsサーバーは、セルフマネージドのOperational Insightsクラスター専用です。
AIエージェントにデータベースへの書き込みを許可しても安全ですか? デフォルトでは安全ではありません。書き込みツールは読み込まれず、変更を伴うSQL++はブロックされます。書き込みを有効にした場合でも、個々のツールを無効にしたり、確認を必須にしたりできます。ただし、実際のセキュリティ境界となるのはCouchbaseユーザーのRBAC権限です。安全性の制御を参照してください。
SQL++を知っている必要がありますか? いいえ。平易な言葉で質問すれば、アシスタントがrun_sql_plus_plus_query用のSQL++を作成します。クエリプランの説明を求めたり、Index Advisorに推奨事項を尋ねたりすることもできます。
STDIOとStreamable HTTPのどちらを使うべきですか? ローカルの単一クライアントにはSTDIOを使用します。OAuthを使って複数のクライアントで1つのサーバーを共有する場合は、Streamable HTTPを使用します。トランスポートを参照してください。
Couchbaseによる公式サポートはありますか? はい、Couchbase AI Data Planeライセンスがある場合にサポートされます。ライセンスがない場合、CouchbaseのエンジニアはGitHubのIssueを通じてベストエフォートで支援します。サポートポリシーを参照してください。
コントリビューション
バグ修正、機能、ドキュメントなどの貢献を歓迎します。バグの報告やサポートの依頼は、GitHub Issueを作成してください。
開発環境のセットアップ、lint、テスト、プロジェクト構成、ワークフローについてはCONTRIBUTING.mdを参照してください。まずは次の手順を実行します。
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh
統合テストは稼働中のクラスターに対して実行されます。CB_CONNECTION_STRING、CB_USERNAME、CB_PASSWORDをエクスポートし、必要に応じてCB_MCP_TEST_BUCKETも設定してください。Operational InsightsのテストではCB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORDも使用します。これらが設定されていない場合、テストはスキップされます。その後、次を実行します。
uv run --extra dev pytest tests/integration -v
使用データ、LLMのリスク、サポートポリシー
使用データの収集
この製品は、使用状況とパフォーマンスのデータ(製品名やバージョンなど)およびブラウザー情報(IP アドレスなど)(総称して「使用状況データ」)を自動的に収集します。Couchbase は、使用状況データと、お客様が Couchbase に提供するその他のデータ(ユーザー名やメールアドレスなど)を、製品の開発と改善、および営業・マーケティング活動に活用します。Couchbase 製品に保存されたデータにアクセスしたり、収集したりすることはありません。使用状況データは、全体的な使用パターンを把握し、製品をより便利にするために使用します。Couchbase による情報の収集、保護、処理の詳細については、https://www.couchbase.com/privacy-policy. で閲覧できる Couchbase プライバシーポリシーをご覧ください。
LLM に関連するリスク
- 大規模言語モデルや類似技術の使用には、不正確または有害な出力が生成される可能性など、リスクが伴います。
- Couchbase は、そのような出力の品質や正確性を確認または評価しません。また、そのような出力は Couchbase の見解を反映していない場合があります。
- 大規模言語モデルや関連技術を使用するかどうかの判断、およびそれらの使用に適用されるライセンス条項、利用規約、組織のポリシーの遵守については、お客様が単独で責任を負います。
サポートポリシー
Couchbase MCP Server はオープンソースであり、Couchbase のエンジニアが保守しています。サポートの利用方法は、使用方法によって異なります。
- コミュニティでの利用 — GitHub issue を作成して、バグの報告、質問、機能のリクエストを行ってください。Couchbase のエンジニアがリポジトリを監視し、可能な範囲で対応しますが、応答時間の保証はありません。Couchbase サポートポータルでは、コミュニティでの利用に関するサポートは提供していません。
- エンタープライズサポート — Couchbase AI Data Plane のライセンスを取得すると利用できます。このライセンスには Couchbase Agent Memory と Couchbase Agent Catalog も含まれます。ライセンスをお持ちのお客様は、通常の Couchbase サポート窓口を通じてサポートを受けられます。
本プロジェクトをご利用いただき、貢献してくださりありがとうございます!