Claude CodeでCouchbaseプラグインを使い、MCPサーバーとスキルで稼働中クラスタを扱う
CouchbaseプラグインはMCPサーバーと4つのスキルを同梱し、稼働中のクラスタでSQL++の実行、インデックス最適化、データモデル設計を進めます。導入手順、接続設定、読み取り専用モードの扱いをまとめます。
Couchbaseプラグインは、Couchbase社が出しているプラグインで、Couchbase MCPサーバーと4つのスキルを1回の導入でClaude Codeに入れられます。マーケットプレイスのページには「Anthropic verified」の表示があり、説明文は「稼働中のクラスタに接続し、データを調べ、SQL++を書いて実行し、クエリとGSIインデックスを最適化し、データモデルを設計する」という内容です。
要点は、モデルの記憶ではなく実クラスタのスキーマ・データ・インデックスを見てから答えさせる点にあります。導入は2コマンドですが、その後に接続情報の設定が要ります。ここを飛ばすと動かないので、手順と注意点を順に書きます。
Couchbaseプラグインが入れるもの
プラグインのマニフェストは、スキルのディレクトリとMCPサーバーの設定ファイルを指しています。バージョンは0.1.1、ライセンスはApache-2.0です。
プラグインに同梱される2種類の部品
MCPサーバー
uvxでcouchbase-mcp-serverを起動する設定が入っています。バージョンは1.0.1.post1に固定されています。4つのスキル
接続設定、自然言語からのSQL++生成、クエリ最適化、データモデル設計の4つです。
スキルは次の4つで、いずれも稼働中のクラスタをMCPサーバー経由で参照する前提です。
| スキル | 担当 |
|---|---|
| couchbase-mcp-setup | 担当CB_*環境変数の設定。接続が失敗したときの案内役 |
| couchbase-natural-language-querying | 担当自然言語をSQL++に変換し、実クラスタで実行 |
| couchbase-query-optimizer | 担当EXPLAINプランの読み解き、GSIインデックス設計、遅いクエリの切り分け |
| couchbase-data-modeling | 担当JSONのスキーマ設計、埋め込みか参照かの判断、ドキュメントキーの形 |
同じリポジトリのマーケットプレイスには、モバイル向けの別プラグイン(couchbase-mobile)も登録されています。iOSやAndroidのアプリをCouchbase LiteとCapella App Servicesで組むもので、本記事のサーバー側プラグインとは別物です。
導入前に揃えるもの
MCPサーバーは、次の条件を前提にしています。
- Python 3.10から3.14
- Couchbase Server 7.6以降(オペレーショナルクラスタ)。Capellaの無料枠でもよい
uvまたはDocker(uvが推奨)- 対象クラスタにMCPサーバーを動かすマシンから届くこと
対応外のサービスも明記されています。Couchbase Analytics、Sync Gateway、Couchbase Lite、Capella AI Servicesは使えません。Analyticsを使うワークロードをこのプラグインで扱うことはできない、と先に知っておくと遠回りしません。
認証はユーザー名とパスワードのベーシック認証のほか、mTLSのクライアント証明書にも対応しています。ただしプラグイン同梱の設定が受け取る環境変数は、接続文字列・ユーザー名・パスワードの3つです。
導入手順
Claude Codeのセッション内で、マーケットプレイスを追加してからプラグインを入れます。
/plugin marketplace add Couchbase-Ecosystem/agent-skills
/plugin install couchbase@couchbase-pluginsマーケットプレイス名はcouchbase-pluginsで、リポジトリ自体がプラグインの配布元を兼ねています。導入後にcouchbase-mcp-setupスキルを呼ぶと、CB_*環境変数の設定を案内してもらえます。
接続情報を渡す
接続に必要な値は3つです。
| 環境変数 | 内容 | 例 |
|---|---|---|
CB_CONNECTION_STRING | 内容接続文字列 | 例couchbases://cb.abc.cloud.couchbase.com(Capella)、couchbase://localhost(ローカル) |
CB_USERNAME | 内容データベースユーザー | 例Capellaでは画面のログイン名ではなく「Cluster Access Name」 |
CB_PASSWORD | 内容そのユーザーのパスワード | 例 |
つまずきやすい点が2つあります。Capellaは暗号化接続が必須で、couchbases://(sが付く)でないと拒否されます。もう1つは、Capellaの管理画面にログインするアカウントと、データベースに入るためのクラスタアクセス用ユーザーが別物だという点です。
同梱設定に環境変数を引き継ぐ方法
プラグイン同梱の設定ファイルは、CB_CONNECTION_STRING、CB_USERNAME、CB_PASSWORDをClaude Codeを起動したシェルの環境からそのまま受け取ります。つまり、起動前にエクスポートしておく方式です。
export CB_CONNECTION_STRING="couchbases://..."
export CB_USERNAME="mcp_reader"
export CB_PASSWORD="..."
claude起動後に環境変数を足しても反映されないので、Claude Codeの再起動が要ります。プロジェクトごとに分けたいときは、リポジトリに入れない.envrc(direnv)で持ちます。グローバルな~/.zshrcに書くと、他のシェルやプロジェクトにも漏れる点に注意が要ります。
claude mcp addで登録し直す方法
認証情報をシェルの環境に出したくないときは、ローカルスコープで登録する方法があります。~/.claude.jsonにだけ保存され、サーバープロセスにだけ渡されます。
claude mcp add couchbase --scope local \
-e CB_CONNECTION_STRING="couchbases://..." \
-e CB_USERNAME="mcp_reader" \
-e CB_PASSWORD="..." \
-e CB_MCP_READ_ONLY_MODE="true" \
-- uvx --from "couchbase-mcp-server==1.0.1.post1" couchbase-mcp-serverスコープの優先順位はlocal、project、user、プラグインの順で、ローカルスコープの登録がプラグイン同梱の定義より優先されます。projectスコープは認証情報が.mcp.jsonに書かれてリポジトリへコミットされるため使いません。
すでにcouchbaseという名前のサーバーが登録済みなら、先にclaude mcp remove couchbaseで消してから足してください。同じ名前の登録が2か所にあると、意図しない方が応答することがあります。
組織の管理設定でプラグイン以外のMCP追加が止められている環境では、このclaude mcp addは通りません。症状と原因はclaude mcp addが失敗する理由にあります。その場合はプラグイン同梱の設定に環境変数を渡す方式を選ぶことになります。プラグイン側でサーバーを同梱する仕組みの背景はプラグインに同梱されたMCPサーバーの仕組みで扱っています。
接続の確認
設定後はClaude Codeを再読み込みか再起動してから、疎通を確かめます。スキルは最初のクラスタ操作の前に、次の順で接続を見ます。
get_server_configuration_statusでサーバーの状態とconnections.cluster_connectedを読む。クラスタへの接続は開かず、即座に返る- 未接続なら
test_cluster_connectionを1回だけ呼ぶ。長いタイムアウト例外ではなく、statusとmessageの形で返る - 到達できなければ再試行せず、
couchbase-mcp-setupに引き継ぐ
読み取りの前に1回だけ接続を確かめる作りなので、認証情報の誤りは最初の1往復で表に出ます。
読み取り専用モードと権限の設計
実際の運用で一番効くのが、書き込みの扱いです。
CB_MCP_READ_ONLY_MODE=trueのとき、KV書き込み用のツールはそもそも読み込まれません。SQL++のINSERT、UPDATE、DELETE、MERGEとDDLも拒否されます。プラグイン同梱の設定はこの値の既定をtrueにしています。
ただし、読み取り専用モードやツールの無効化は、あくまでモデルの振る舞いを導く層です。強制力を持つのはデータベースのRBAC(役割ベースのアクセス制御)で、セキュリティのページはこちらを「authoritative(決定的な)」な制御と位置づけています。
- MCPサーバー専用のデータベースユーザーを作る。共有アカウントや管理者アカウントは使わない
- 書き込みが不要ならData ReaderやQuery Selectなどの読み取り系ロールに絞る
- 権限はクラスタ全体ではなく特定のバケットに限定する
couchbases://でTLS接続にする
Capellaでは、読み取りだけの「Basic Cluster Access」資格情報を作るのが手軽です。data_readerやquery_selectといった細かいロールの付与は、有料プランの高度な設定という扱いです。
追加の安全弁として、CB_MCP_DISABLED_TOOLSにツール名(カンマ区切り)を渡すと該当ツールを外せます。CB_MCP_CONFIRMATION_REQUIRED_TOOLSに挙げたツールは、実行前に確認を求める設定になります。後者の効き方はクライアントによって変わります。
4つのスキルの使いどころ
導入が済んだら、次のように頼むと該当スキルが選ばれます。以下は依頼文の例で、返答の再現ではありません。
自然言語で実クラスタに質問する
travel-sampleのinventoryスコープで、経路数が多い航空会社の上位5社を出して
couchbase-natural-language-queryingは、SQL++を書く前に実クラスタの構造を調べます。バケット一覧、get_schema_for_collectionによるスキーマの推測、数件のサンプルドキュメント、list_indexesでのインデックス確認です。
スキーマの推測はドキュメントの一部を標本抽出して行うため、まれなフィールドを取りこぼすことがあります。スキルはこの結果を「強い手がかり」として扱い、完全な目録とは見なしません。
Couchbaseは存在しないフィールドを指定してもエラーにならず、MISSINGを返します。フィールド名の綴り違いは、空の結果として静かに現れます。そのため事前のスキーマ照合に意味があります。
ツール呼び出しにも決まりがあります。run_sql_plus_plus_queryは、バケット名とスコープ名を別々の引数で受け取ります。クエリ本体には裸のコレクション名を書き、FROM `travel-sample`.inventory.route のようにキースペースを文字列に埋めるのは誤りです。
run_sql_plus_plus_query(
bucket_name="travel-sample", scope_name="inventory",
query="SELECT airline, COUNT(*) AS routes FROM route
GROUP BY airline ORDER BY routes DESC LIMIT 5")このスキルは読み取り専用で、書き込みやDDLは生成しません。ユーザー定義関数については、CREATE FUNCTION文を提示するだけで実行しません。全文検索、ベクトル検索、意味的な類似検索も対象外で、これらはCouchbaseの検索サービスの領分です。
遅いクエリを調べて直す
このクエリが遅い。EXPLAINを見て、インデックスを提案して
couchbase-query-optimizerは、遅いクエリの診断とCREATE INDEX文の提案までを担当します。インデックスを作る操作は行いません。MCPサーバーが読み取り専用なので、DDLは実行できないからです。提案されたDDLは、Query Workbenchかcbqで人が流す前提です。
スキルの冒頭に並ぶ原則の一部を抜き出します。
- 80%の性能問題は20%のクエリから来る。
system:completed_requestsか、MCPのget_longest_running_queries、get_most_frequent_queriesで、先に対象を絞る - インデックスの先頭キーがWHERE句に出ないと、そのインデックスは選ばれない
- ホットなクエリはカバリングインデックスにする。EXPLAINに
coversがあり、Fetch演算子がないのが目印 docTypeのような値の種類が少ないフィールド単独のインデックスは避け、部分インデックスにする- 本番環境ではプライマリスキャン(全件走査に相当)を避ける
- 配列インデックスでは、クエリの形とインデックスの形を合わせる。UNNESTは
CREATE INDEX ... FOR <var> IN ...と同じ束縛変数名にする
サーバー側には、遅いクエリ探しに使えるツールが揃っています。get_queries_not_selective、get_queries_not_using_covering_index、get_queries_using_primary_index、get_queries_with_largest_response_sizes、get_queries_with_large_result_countなどです。いずれもsystem:completed_requestsを引くので、「本番でプライマリインデックスに頼っているクエリはあるか」を一覧で出させる使い方ができます。
落とし穴
インデックスで直らないクエリがある
クラスタ全体に近い範囲の集計やGROUP BY、選択的な条件のない大きな結合は、どんなインデックスでも速くなりません。このスキルはその種のクエリをQuery Serviceの向かない処理として扱い、ADVISEも提案を出せないと説明しています。「インデックスを足せば解決する」と決め打ちせず、処理の置き場所から見直す場面があります。
データモデルを設計する
注文と明細をCouchbaseでどう持つか、MongoDBからの移行も踏まえて相談したい
couchbase-data-modelingは、「一緒にアクセスされるデータは一緒に保存する」を基本に置きます。ただしCouchbaseではキーによるKVの取得が安いので、参照のほうが他のデータベースより割安になりやすい、という前提があります。
設計の前に、次の問いを順に通します。
- アプリが最も頻繁に読むのは何か
- 一緒に変更されるのは何か
- アクセスの単位は何か(ドキュメントは原子的な単位であり、一部だけ頻繁に必要なら別ドキュメントの可能性が高い)
- データの寿命はどうか(永続、TTL付きのセッション、期間限定の時系列は別のコレクション、場合によっては別のバケットに置く)
キー設計、ドキュメントの形、バケット・スコープ・コレクションの境界、時系列とTTL、アンチパターン、リレーショナルからの移行など、参照資料が分かれています。コレクションの作成やシードにはユーザーの明示的な承認が要り、読み取り専用モードではそもそもブロックされます。
同種のプラグインとの違い
Greptileプラグインのように、外部サービスのMCPサーバーへ接続するだけのプラグインとは、構成が違います。Couchbaseは接続先のMCPサーバーに加えて、データ作業の進め方を書いたスキルが同梱され、スキル側が接続確認、スキーマ確認、読み取り専用の遵守といった手順をあらかじめ握っています。スキルには「接続できなければ再試行せずセットアップに回す」「推測でフィールド名を書かない」といった手順が書かれているので、ツールだけを渡す構成より進め方の迷いが減ります。
使う前の確認リスト
- 自分のクラスタはCouchbase Server 7.6以降か。Analyticsなど対象外のサービスを使っていないか
- MCPサーバー専用の最小権限ユーザーを用意したか
couchbases://で接続し、Capellaならクラスタアクセス用の名前を使っているか- 書き込みが必要ないなら
CB_MCP_READ_ONLY_MODE=trueを明示したか - 認証情報を
projectスコープの.mcp.jsonや共有の設定ファイルに書いていないか - 1つのサーバーは1つのクラスタに固定されるので、別のクラスタを見るときは接続文字列と資格情報を差し替えて再起動する
まとめ
CouchbaseプラグインはMCPサーバーとスキルをまとめて入れ、導入は/plugin installの2コマンドで済みます。実際の手間は接続情報の設定にあり、最小権限のデータベースユーザーと読み取り専用モードの明示が最初の分かれ目です。そのうえで、SQL++の生成とインデックスの提案は実クラスタの構造を見てから出させ、DDLは人が流す、という分担で使うと安全に回せます。