Couchbase

官方

使用自然語言與儲存在 Couchbase 叢集中的資料進行互動。

你可以用 Couchbase MCP 做什麼?

  • 探索叢集資料 — 列出 bucket、scope 和 collection,接著推斷像 orders 這類 collection 的結構描述。
  • 執行 SQL++ 查詢 — 對 bucket 和 scope 執行唯讀 SQL++ 查詢,並說明查詢計畫。
  • 檢視文件 — 依 ID 擷取文件,或讀取特定子文件路徑,而不載入整份文件。
  • 檢查叢集健康狀態 — 回報叢集健康狀態、執行中的服務,以及連線診斷資訊。
  • 分析查詢效能 — 找出執行時間最長、最常執行或未使用涵蓋索引的查詢。
  • 搜尋與向量查詢 — 對已設定的索引執行全文搜尋和向量相似度查詢。

文件

Couchbase MCP Server

Couchbase MCP Server 是一個自架的 MCP Server,可讓 AI 代理程式連線至 Couchbase Servers(無論是託管於 Capella 或自行管理)或 Operational Insights Enterprise 中的資料並與之互動。它提供多種類別的工具,包括叢集健康狀態、資料結構描述、查詢等,並透過唯讀模式和細緻的工具停用功能提供安全控制。它支援 STDIO 和 Streamable HTTP 傳輸,以及 OAuth 功能。

Couchbase MCP Server 以 Python Package Index (PyPI) 套件形式發佈,也可透過 Docker 取得。若取得 Couchbase AI Data Plane 授權,即可獲得 Couchbase MCP Server 的企業支援,並有權使用 Couchbase Agent Memory 和 Couchbase Agent Catalog,且享有企業支援。

Docs License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

完整文件:docs.couchbase.com/mcp-server

Couchbase Server MCP server

目錄

為何選擇 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 適用於本機桌面用戶端;Streamable HTTP 則支援選用的 OAuth 2.1(任何會發佈 JWKS 的 IdP:Auth0、Okta、Keycloak、Entra、Cognito 等)、健康檢查,以及供共用部署使用的稽核記錄。Operational server 也可執行多個工作者以使用更多 CPU 核心。
  • 支援任何 MCP 用戶端 — 已使用 Claude Desktop、Cursor、Windsurf、VS Code 和 JetBrains AI Assistant/Junie 進行測試。

連線後,您可以提出以下問題:

  • 「我有哪些 buckets、scopes 和 collections?orders collection 的結構描述為何?」
  • 「找出 users 中符合 status = 'active' 的 10 份最新文件。」
  • 「過去一小時最慢的 5 個查詢是哪些?其中是否有查詢缺少涵蓋索引?」
  • 「此叢集是否健康?目前正在執行哪些服務?」
  • 「使用以下欄位在 products 中插入新文件:…」(需要 CB_MCP_READ_ONLY_MODE=false)

選擇伺服器

此套件提供兩個 MCP 伺服器。每個伺服器都透過自己的子命令啟動、連線至不同類型的叢集,並提供各自的工具。請選擇符合您叢集的伺服器,依照對應章節進行設定並了解其工具,再參閱通用組態設定兩者共用的選項。若要同時使用兩者,請在 MCP 用戶端中將它們分別註冊為獨立伺服器。

Operational serverOperational 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 連接埠80008001
預設記錄檔mcp_server.logmcp_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 叢集。

Operational 快速入門

您需要一個正在執行的 Couchbase 叢集 — Capella 免費層是最快的取得方式(您可以匯入範例資料集)— 以及一個 MCP 用戶端。將以下其中一種組態新增至用戶端(各用戶端的設定位置請參閱用戶端設定)。如果用戶端已設定其他伺服器,請將 couchbase 加入現有的 mcpServers 物件。

透過 PyPI 使用 uvx(需要 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 連線與驗證

請使用使用者名稱和密碼或用戶端憑證(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-pathmTLS 驗證
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 工具

唯讀模式預設為開啟,啟用時不會載入寫入工具(以 ✏️ 標示)。以 🖥️ 標示的工具僅適用於自行管理的環境 — 它們使用 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_reportSDK 快取的連線診斷資訊,不進行主動網路探測
get_cluster_metrics 🖥️指定歷史時間範圍內的叢集統計資料(stats-range 端點)
get_cluster_tasks 🖥️目前正在執行的工作 — 重新平衡、壓縮、XDCR、索引建置。需要 ro_admin
get_cluster_health_snapshot 🖥️各節點的健康狀態:服務拓撲、成員資格、協調器及健康狀態彙總。需要 ro_admin
get_bucket_config 🖥️一個或所有 bucket 的組態與即時狀態 — 配額、淘汰策略、副本、持久性、儲存、壓縮。需要 ro_admin
get_cluster_system_events 🖥️系統事件記錄(組態變更、故障轉移、重新平衡、重新啟動),可使用 since_time 指定時間範圍。需要 Full Admin 或 Cluster Admin
discover_tool_input_values 🖥️查詢其他工具所需的確切輸入值(例如 get_cluster_metrics 的所有指標名稱)。可離線使用

資料模型與結構描述探索

工具說明
get_buckets_in_cluster列出叢集中的所有 buckets
get_scopes_in_bucket列出 bucket 中的所有 scopes
get_collections_in_scope列出 scope 中的所有 collections(需要 Query 服務)
get_scopes_and_collections_in_bucket列出 bucket 中的所有 scopes 和 collections
get_schema_for_collection推斷 collection 的結構
create_scope ✏️在 bucket 中建立 scope(Server 7.6+ 和 Capella)
create_collection ✏️在現有 scope 中建立 collection(Server 7.6+ 和 Capella)
delete_scope ✏️刪除 scope 及其所有 collections — 永久刪除
delete_collection ✏️刪除 collection 及其所有文件 — 永久刪除

文件(KV)操作

工具說明
get_document_by_id依 ID 取得文件
lookup_subdocument讀取指定路徑、檢查是否存在或計算數量,而不擷取整份文件
upsert_document_by_id ✏️依 ID Upsert 文件
insert_document_by_id ✏️插入新文件(若文件已存在則失敗)
replace_document_by_id ✏️取代現有文件(若文件不存在則失敗)
delete_document_by_id ✏️依 ID 刪除文件
mutate_subdocument ✏️修改現有文件中的路徑(upsert、insert、replace、remove、陣列操作、計數器)

查詢與索引

工具說明
run_sql_plus_plus_query執行範圍限定於 bucket 和 scope 的 SQL++ 查詢 — 直接使用 collection 名稱(SELECT * FROM users)。唯讀模式會封鎖修改資料的陳述式
explain_sql_plus_plus_query產生並評估 EXPLAIN 計畫:中繼資料、擷取的計畫及分析結果
get_index_advisor_recommendations為 SQL++ 查詢提供 Index Advisor 建議
list_indexes列出索引及其定義,可依 bucket/scope/collection/name 篩選;標示向量索引(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 ✏️在 collection 上建置所有延後的索引
drop_index ✏️刪除 GSI 索引(純量或向量)

全文搜尋(FTS)

需要 Couchbase Server 7.6+ 和 Search 服務。支援 scope 層級和叢集層級(舊版)索引:scope 層級索引請同時傳入 bucket_name 和 scope_name,或兩者皆省略。

工具說明
list_search_indexes列出 Search 索引 — 叢集層級、每個 bucket 或每個 scope
get_search_index_definition單一 Search 索引的完整定義(mappings、analyzers、plan params)
run_search使用原始 JSON 主體執行任何非向量 FTS 查詢;explain=true 會傳回執行計畫
upsert_search_index ✏️建立或更新 Search 索引,包括向量欄位 mappings。更新會觸發完整重建 — 傳入目前的 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 自己的管理 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 和啟動記錄中,將它們與您自己的已停用工具一併回報。以 SDK 為基礎的工具(例如 get_cluster_health_and_services 和 get_client_connectivity_report)仍可使用。

工具所需端點
get_cluster_metricsManagement REST(/pools/default/stats/range)
get_cluster_tasksManagement REST(/pools/default/tasks)
get_bucket_configManagement REST(/pools/default/buckets[/<name>])
get_cluster_health_snapshotManagement REST,以及每個節點的端點
get_cluster_system_eventsManagement REST(/events)
get_index_statsIndex Service REST(每個 indexer 的 /api/v1/stats)
get_cluster_query_vitalsQuery Service REST(/admin/vitals)
get_active_queriesQuery Service REST(/admin/active_requests)
delete_active_queryQuery 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必要選用備註
capellaCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL、CB_MCP_EMBEDDING_MODEL_ENDPOINT—Capella Model Service。CB_MCP_EMBEDDING_MODEL_ENDPOINT 是您部署專屬的 URL(例如 https://<id>.ai.couchbase.com),可在 Capella 的 AI Data Plane > Models 中找到
openaiCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT設定端點即可使用與 OpenAI 相容的本機伺服器(Ollama、vLLM、LM Studio)
cohereCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
voyageCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
bedrockCB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID、CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY、CB_MCP_EMBEDDING_MODEL_AWS_REGIONAmazon Titan embedding 模型(例如 amazon.titan-embed-text-v2:0)— 提供者會傳送 Titan 的 inputText 請求格式,因此目前尚不支援其他 Bedrock embedding 模型,例如 Cohere Embed。省略憑證即可使用預設 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-stringCouchbase 叢集的連線字串必要
CB_USERNAME--username可存取必要 bucket、用於基本驗證的使用者名稱必要(或 mTLS 所需的用戶端憑證和金鑰)
CB_PASSWORD--password基本驗證的密碼必要(或 mTLS 所需的用戶端憑證和金鑰)
CB_CLIENT_CERT_PATH--client-cert-pathmTLS 驗證的用戶端憑證檔案路徑使用 mTLS 時必要(或需要使用者名稱和密碼)
CB_CLIENT_KEY_PATH--client-key-pathmTLS 驗證的用戶端金鑰檔案路徑使用 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、httpstdio
CB_MCP_HOST--hostHTTP 傳輸模式的主機127.0.0.1
CB_MCP_PORT--portHTTP 傳輸模式的連接埠8000
CB_MCP_WORKERS--workershttp 傳輸模式的伺服器工作程序數量。值大於 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-levelMCP 伺服器的記錄層級: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-mbERROR 記錄檔的輪替大小,以 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-mbWARNING 記錄檔的輪替大小,以 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-mbINFO 記錄檔的輪替大小,以 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-mbDEBUG 記錄檔的輪替大小,以 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-countERROR 記錄檔保留的輪替備份檔數量;覆寫 ERROR 的全域數量繼承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countWARNING 記錄檔保留的輪替備份檔數量;覆寫 WARNING 的全域數量繼承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countINFO 記錄檔保留的輪替備份檔數量;覆寫 INFO 的全域數量繼承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countDEBUG 記錄檔保留的輪替備份檔數量;覆寫 DEBUG 的全域數量繼承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uri用於驗證 bearer JWT 的身分識別提供者 JWKS 端點。與簽發者和對象一同設定時會啟用 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-algorithmJWT 簽署演算法:可選 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覆寫視為「讀取」存取權的 OAuth 範圍標籤(會在 PRM 中公告,並與權杖的 scope/scp 宣告比對)。若 IdP 無法產生標準形式,請使用此設定couchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-label覆寫視為「寫入」存取權的 OAuth 範圍標籤;語意與讀取標籤相同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 — 絕不寫入 stdout,因為 stdio 上的 JSON-RPC 通訊協定會使用 stdoutconsole
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),或每行一個 ID 的檔案。僅可抑制可篩選的事件無
CB_MCP_EMBEDDING_MODEL_PROVIDER--embedding-model-providerrun_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-idAWS 存取金鑰 ID,僅適用於 bedrock 提供者。省略時會使用預設 AWS 憑證鏈無
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyAWS 秘密存取金鑰,僅適用於 bedrock 提供者無
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionAWS 區域,僅適用於 bedrock 提供者。未設定時會回退至 AWS SDK 自身的區域解析機制無

Operational Insights 伺服器

operational-insights 伺服器會連線至自我管理的 Operational Insights 叢集。Operational Insights 是一種即時分析資料庫(RT-OLAP),適用於即時應用程式和營運智慧。此伺服器不適用於 Capella。它使用 couchbase-operational-insights SDK。此伺服器以獨立程序執行,與作業伺服器分開。

[!IMPORTANT] CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING 是 HTTP(S) URL,不是 couchbase:// 連線字串 — 例如 http://localhost:8095,或透過 TLS 使用的 https://<host>:18095。這是最常見的設定錯誤。

Operational Insights 快速入門

透過 uvx 從 PyPI 安裝:

{
  "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 連線與驗證

環境變數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-pathmTLS 的用戶端憑證 — 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,因此兩個伺服器可以並行執行。
  • 僅支援一個工作者 (CB_MCP_WORKERS=1),因為非同步查詢控制代碼會存放在程序記憶體中。
  • 沒有 CB_MCP_EMBEDDING_MODEL_* 選項。

Operational Insights 工具

除了 get_server_configuration_status 以外,所有名稱都會加上 operational_insights_ 前綴,因此兩個伺服器可以在同一個用戶端中註冊而不會發生衝突。啟用唯讀模式(預設)時,寫入工具(標記為 ✏️)不會載入。

伺服器狀態

工具說明
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 這三項,並可選擇傳入 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,將工具清單縮減至最低限度。
  • 要求敏感工具在執行前取得確認 — 請參閱要求確認。

以下控制分為三個層級,範圍由廣至窄。請搭配使用,但請記住,這些控制都不能取代 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 會將工具完全從探索清單中移除。它接受以逗號分隔的清單,或每行列出一個工具名稱的檔案(# 開頭的行會視為註解):

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多個用戶端共用一個伺服器;支援 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"
    }
  }
}

多個工作者

單一程序最多約使用一個 CPU 核心。--workers N (CB_MCP_WORKERS) 會在相同主機和連接埠後方執行 N 個程序;可用的核心數是良好的起始設定。只有作業伺服器支援工作者。使用多個工作者時:

  • 必須使用 http 傳輸方式,且伺服器會以無狀態 HTTP 模式執行,因為用戶端的請求可能會送達不同工作者。也可以在單一工作者上設定 --stateless-http=true,例如在沒有黏性工作階段的負載平衡器後方使用。
  • 無法使用需要確認的工具。
  • 每個程序都會寫入自己的記錄檔,檔名包含主機和程序 ID (mcp_server.<host>.<pid>.info.log) — 監督程序和每個工作者各有一組記錄檔。

負載平衡器

您可以在負載平衡器後方執行多個伺服器執行個體。每個執行個體都會將自己的 MCP 工作階段保存在記憶體中,因此負載平衡器的設定會決定哪些功能可用:

負載平衡器伺服器設定需要確認的工具
黏性工作階段,依據 Mcp-Session-Id 請求標頭路由單一工作者、有狀態(預設)支援
無黏性工作階段--stateless-http=true不支援 — 若已設定,伺服器會拒絕啟動
  • 沒有黏性工作階段時,有狀態執行個體會拒絕所有工作階段建立於其他執行個體的請求。此時請使用無狀態模式。
  • 請依據 Mcp-Session-Id 標頭路由,而非 Cookie。許多 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 資源伺服器,根據身分識別提供者的 JWKS 驗證 bearer JWT。它適用於任何會發布 JWKS 的 OAuth 2.1/OIDC 提供者,且不會簽發權杖或管理使用者。在 stdio 上會忽略 OAuth 設定。

  • 只有在 CB_MCP_OAUTH_JWT_JWKS_URI、CB_MCP_OAUTH_JWT_ISSUER 和 CB_MCP_OAUTH_JWT_AUDIENCE 三者都已設定時,OAuth 才會啟用;只設定其中部分項目會導致啟動失敗。
  • CB_MCP_OAUTH_MCP_BASE_URL 也會發布 RFC 9728 受保護資源中繼資料,讓用戶端能探索授權伺服器。
  • 存取權由權杖的 scope/scp 宣告中的兩個範圍控管:couchbase-mcp:read(讀取工具)和 couchbase-mcp:write(寫入工具)。完整存取權需要兩者。若您的 IdP 無法產生這些標籤,可使用 CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL 重新命名。兩個伺服器使用相同標籤,因此一份 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 時,每個層級會在 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

記錄採用 JSON Lines 格式,使用與 Couchbase Server 和 Sync Gateway 相同的欄位詞彙:

{"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"}
稽核的運作方式
  • 身分 — real_userid 是呼叫者:oauth(權杖主體)、local(stdio 模式下的 OS 使用者),或 anonymous(未使用 OAuth 的 HTTP;啟動時會發出警告)。
  • 關聯 — cid 會將同一個請求的所有記錄分組,並以 SQL++ client_context_id 的形式傳送,因此可與 Couchbase Server 的 clientContextId 精確連結。刻意不提供工作階段識別碼。
  • 事件 — 固定且編號的目錄(生命週期、初始化、權杖遭拒、範圍遭拒、唯讀封鎖、確認遭拒/略過,以及每個工具類別各自的讀取/寫入事件)。query 和 search 是例外:每個都記錄為單一事件,而非讀取/寫入事件,因為對於由陳述式驅動和搜尋介面,無法可靠地區分兩者。向量操作包含在這兩個類別中。完整目錄以套件中的 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)也無法停用:每個類別的單一事件涵蓋讀取和寫入,因此停用它會遺失變更記錄。
  • 輪替 — 依大小(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)會限制單一檔案的備份數量。每個新程序都會寫入新檔案,且不會清除舊檔案,因此請妥善規劃磁碟區大小,或清理舊的 audit.*.log* 檔案。
  • 失敗時繼續服務 — 若無法寫入檔案,伺服器會繼續提供服務並計算遺失的記錄數;get_server_configuration_status 會回報 written / dropped / write_errors。
  • 工具引數 — 只有使用 CB_MCP_AUDIT_LOG_TOOL_ARGS=true 時才會記錄,並會在啟動時發出警告。此版本不會遮蔽資料,因此包括完整文件本文在內的引數都會以原樣寫入。

用戶端設定

每個用戶端都需要在自己的設定位置,使用作業伺服器或 Operational Insights快速入門中的伺服器設定。以下範例使用作業伺服器。

Claude Desktop
  1. 開啟設定檔(請參閱 MCP 快速入門指南):
    • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows:%APPDATA%\Claude\claude_desktop_config.json
  2. 在 mcpServers 下新增伺服器,然後重新啟動 Claude Desktop。

**記錄:**macOS ~/Library/Logs/Claude,Windows %APPDATA%\Claude\Logs。請參閱 MCP 疑難排解指南。

Cursor
  1. 前往 Cursor Settings > Tools & Integrations > MCP Tools(請參閱 Cursor 的 MCP 文件),或使用一鍵式在 Cursor 中安裝連結 — 然後替換佔位連線字串和認證資料。
  2. 在 mcpServers 下新增設定並儲存。
  3. 重新整理 MCP 伺服器清單,確認 couchbase 已啟用。

**記錄:**在底部面板中開啟 Output,並選取 Cursor MCP。

Windsurf Editor
  1. 開啟 Command Palette > Windsurf MCP Configuration Panel,或 Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers(請參閱 Windsurf 的 MCP 文件)。
  2. 按一下 Add Server > Add custom server,貼上設定並儲存。
  3. 重新整理伺服器清單,確認 couchbase 已啟用。
VS Code

VS Code 使用 servers 作為頂層索引鍵,而非 mcpServers。將設定放入工作區的 .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
  1. 安裝 AI Assistant 或 Junie 外掛程式。
  2. 前往 Settings > Tools > AI Assistant (or Junie) > MCP Server,按一下 +,新增設定並按一下 Apply。
  3. 將游標停留在伺服器狀態上,即可查看其工具。

**記錄:**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,請確認叢集允許連線至執行伺服器的機器。
  • 確認資料庫使用者至少能存取一個 bucket。
  • 如果用戶端找不到 uv/uvx,請在 command 中填入絕對路徑。
  • 從原始碼執行時,請檢查設定中的儲存庫路徑,並在拉取更新後執行 uv sync。
  • 呼叫 get_server_configuration_status,查看伺服器實際解析出的設定,並檢查用戶端記錄(請參閱用戶端設定)。

常見問題

如何將 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,請使用 Streamable HTTP。請參閱傳輸方式。

Couchbase 是否正式支援此功能? 是,需持有 Couchbase AI Data Plane 授權。若沒有授權,Couchbase 工程師會透過 GitHub issues 盡力提供協助。請參閱支援政策。

參與貢獻

歡迎提交貢獻 — 包括錯誤修正、功能和文件。若要回報錯誤或尋求協助,請開啟 GitHub issue。

開發環境設定、程式碼檢查、測試、專案結構和工作流程請參閱 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 問題回報錯誤、提出問題及要求新功能。Couchbase 工程師會監看儲存庫,並盡力回覆,但不承諾回覆時間。Couchbase 支援入口網站無法協助社群使用者。
  • 企業支援 — 可透過授權 Couchbase AI Data Plane 取得,該授權也涵蓋 Couchbase Agent Memory 和 Couchbase Agent Catalog。取得授權的客戶可透過慣用的 Couchbase 支援管道獲得協助。

感謝您使用並為本專案做出貢獻!