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.couchbase.com/mcp-server
目錄
- 為何選擇 Couchbase MCP Server
- 選擇伺服器
- Operational Server
- Operational Insights Server
- 通用組態
- 用戶端設定
- Docker
- 疑難排解
- 常見問題
- 貢獻
- 使用資料、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 適用於本機桌面用戶端;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?
orderscollection 的結構描述為何?」 - 「找出
users中符合status = 'active'的 10 份最新文件。」 - 「過去一小時最慢的 5 個查詢是哪些?其中是否有查詢缺少涵蓋索引?」
- 「此叢集是否健康?目前正在執行哪些服務?」
- 「使用以下欄位在
products中插入新文件:…」(需要CB_MCP_READ_ONLY_MODE=false)
選擇伺服器
此套件提供兩個 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 叢集。
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-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 工具
唯讀模式預設為開啟,啟用時不會載入寫入工具(以 ✏️ 標示)。以 🖥️ 標示的工具僅適用於自行管理的環境 — 它們使用 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 🖥️ | 一個或所有 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_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(每個 indexer 的 /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 是您部署專屬的 URL(例如 https://<id>.ai.couchbase.com),可在 Capella 的 AI Data Plane > Models 中找到 |
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 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-string | Couchbase 叢集的連線字串 | 必要 |
CB_USERNAME | --username | 可存取必要 bucket、用於基本驗證的使用者名稱 | 必要(或 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 | 用於驗證 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-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 | 覆寫視為「讀取」存取權的 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 通訊協定會使用 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),或每行一個 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 伺服器
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-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,因此兩個伺服器可以並行執行。 - 僅支援一個工作者 (
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
- 開啟設定檔(請參閱 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 使用 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
- 安裝 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,請確認叢集允許連線至執行伺服器的機器。
- 確認資料庫使用者至少能存取一個 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 支援管道獲得協助。
感謝您使用並為本專案做出貢獻!