Couchbase

Couchbase MCP Server

Couchbase MCP Server 是一個自架設的 MCP Server，允許 AI 代理程式連線並與 Couchbase 叢集中的資料互動，無論是託管於 Capella 或自行管理。它提供涵蓋叢集健康狀態、資料結構、Key-Value、查詢和效能等類別的工具，並透過唯讀模式和精細的工具停用功能提供安全控制。它支援 STDIO 和 Streamable HTTP 兩種傳輸方式。

Couchbase MCP server 以 Python Package Index (PyPI) 套件形式發布，也可透過 Docker 取得。 Couchbase MCP Server 的企業支援可透過授權 Couchbase AI Data Plane 取得，該授權亦包含 Couchbase Agent Memory 和 Couchbase Agent Catalog 的使用權與企業支援。

如需完整文件，請造訪 mcp-server.couchbase.com。

功能/工具

叢集設定與健康狀態工具

資料模型與結構探索工具

文件 KV 操作工具

查詢與索引工具

查詢效能分析工具

先決條件

• Python 3.10 或更高版本。
• 一個執行中的 Couchbase 叢集。最簡單的入門方式是使用 Capella 免費方案，這是 Couchbase server 的完全託管版本。您可以依照指示匯入其中一個範例資料集，或匯入您自己的資料。
• 已安裝 uv 以執行伺服器。
• 已安裝 MCP 用戶端（例如 Claude Desktop）以將伺服器連線至 Claude。本說明適用於 Claude Desktop 和 Cursor。也可以使用其他 MCP 用戶端。

設定

MCP server 可以從預先建置的 PyPI 套件或使用 uv 從原始碼執行。

從 PyPI 執行

我們為 MCP server 發布了預先建置的 PyPI 套件。

使用預先建置套件為 MCP 用戶端進行伺服器設定

基本驗證

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

或

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

注意：如果用戶端中已使用其他 MCP server，您可以將其新增至現有的 mcpServers 物件。

從原始碼執行

MCP server 可以使用此儲存庫從原始碼執行。

將儲存庫複製到您的本機

git clone https://github.com/couchbase/mcp-server-couchbase.git

使用原始碼為 MCP 用戶端進行伺服器設定

這是 Claude Desktop、Cursor、Windsurf Editor 等 MCP 用戶端的常見設定。

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

注意：path/to/cloned/repo/mcp-server-couchbase/ 應為您本機上已複製儲存庫的路徑。別忘了結尾的斜線！

注意：如果用戶端中已使用其他 MCP server，您可以將其新增至現有的 mcpServers 物件。

MCP Server 的其他設定

伺服器可以使用環境變數或命令列引數進行設定：

唯讀模式設定

CB_MCP_READ_ONLY_MODE 是控制寫入作業的唯一開關：

• 當 true（預設）時：所有寫入作業（KV、Query、scope/collection 管理及索引管理）皆停用。KV 寫入工具（upsert、insert、replace、delete、sub-document mutate）、scope/collection 管理寫入工具（create_scope、create_collection、delete_scope、delete_collection）及索引寫入工具（create_index、build_index、drop_index）不會載入，也無法供 LLM 使用，且修改資料或結構的 SQL++ 查詢會被封鎖。
• 當 false 時：KV、scope/collection 管理及索引寫入工具會載入，且允許 SQL++ 資料/結構修改查詢。

這是建議的安全預設值，可防止 LLM 意外修改資料。

注意：進行驗證時，您需要使用者名稱和密碼，或用戶端憑證與金鑰路徑。您也可以選擇指定用於驗證伺服器憑證的 CA 根憑證路徑。 若同時指定用戶端憑證與金鑰路徑以及使用者名稱和密碼，將使用用戶端憑證進行驗證。

停用工具

您可以停用特定工具，防止它們被載入並暴露給 MCP 用戶端。停用的工具不會出現在工具探索中，也無法被 LLM 呼叫。

支援的格式

以逗號分隔的清單：

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

檔案路徑（每行一個工具名稱）：

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

檔案格式（例如 disabled_tools.txt）：

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

以 # 開頭的行會被視為註解並忽略。

MCP 用戶端設定範例

使用逗號分隔的清單：

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

使用檔案路徑（工具眾多時建議使用）：

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

重要安全注意事項

警告： 僅停用工具並不能保證某些作業無法執行。底層資料庫使用者的 RBAC（角色型存取控制）權限才是權威的安全控制。

例如，即使您停用 upsert_document_by_id 和 delete_document_by_id，仍可透過 run_sql_plus_plus_query 工具使用 SQL++ DML 陳述式（INSERT、UPDATE、DELETE、MERGE）進行資料修改，除非：

• CB_MCP_READ_ONLY_MODE 設定為 true（預設），或
• 資料庫使用者缺乏資料修改所需的 RBAC 權限

最佳做法： 務必在您的 Couchbase 使用者憑證上設定適當的 RBAC 權限，作為主要安全措施。將工具停用作業為引導 LLM 行為及縮小攻擊面的額外層級，而非唯一的安全控制。

工具呼叫的 Elicitation/確認

您可以要求特定工具在執行前取得使用者的明確確認（當 MCP 用戶端支援 elicitation 時）。

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools 支援以下格式：

• 以逗號分隔的清單
• 檔案路徑（每行一個工具名稱，支援 # 註解）

範例：

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

當清單中的工具被呼叫時：

• 若用戶端支援 elicitation，系統會提示使用者確認。
• 若用戶端不支援 elicitation，工具會在不經確認的情況下執行，以維持向後相容。

您也可以使用以下方式檢查伺服器版本：

uvx couchbase-mcp-server --version

記錄

MCP 伺服器預設記錄至 stderr。記錄透過 其他設定 中列出的 CB_MCP_LOG_* 變數進行設定：

• CB_MCP_LOG_LEVEL — 記錄多少內容：info（預設）記錄生命週期事件和工具呼叫，debug 增加詳細的內部資訊，off 停用所有記錄。
• CB_MCP_LOG_SINKS — 記錄寫入何處：stderr（預設）、各層級輪替檔案（file）或兩者。使用 file 時，每個層級會寫入一個檔案（例如 mcp_server.info.log 和 mcp_server.error.log），路徑由 CB_MCP_LOG_FILE 設定。
• 輪替大小 — CB_MCP_LOG_ROTATION_MAX_SIZE_MB 是每個層級檔案輪替的全域大小（以 MB 為單位）。可使用 CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB（ERROR/WARNING/INFO/DEBUG）覆寫個別層級，同樣以 MB 為單位，未設定時繼承全域值。大小為 0（全域或各層級）無效，會回退至預設值（1 MB）並於啟動時顯示警告。CB_MCP_LOG_MAX_BYTES（位元組）已棄用，但為向後相容仍予支援；當同時設定 CB_MCP_LOG_ROTATION_MAX_SIZE_MB 時會被忽略，並於啟動時顯示棄用警告。
• 保留 — CB_MCP_LOG_RETENTION_BACKUP_COUNT 設定每個層級保留多少個輪替備份（不含現用檔案）；預設值 1 保留先前行為。可使用 CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT（ERROR/WARNING/INFO/DEBUG）覆寫個別層級，未設定時繼承全域值。將計數設為 0 可僅保留該層級的現用檔案 — 仍受輪替大小限制（輪替時重設而非備份）。
• 伺服器設定快照 — 當 file sink 啟用時，會將一次性記錄（OS、Python、相依套件版本、傳輸方式、解析後的記錄設定及經遮罩的伺服器設定）以 JSON 寫入專用的 mcp_server_config.log.json 檔案（由 CB_MCP_LOG_FILE 基礎路徑衍生）。每次啟動時會覆寫，因此支援人員永遠有目前的設定，且不會從輪替記錄中滾出。

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

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

更多詳細資訊請參閱文件。

用戶端特定設定

Streamable HTTP 傳輸模式

MCP 伺服器可以 Streamable HTTP 傳輸模式執行，此模式允許多個用戶端透過 HTTP 連線至同一個伺服器執行個體。 在嘗試以此模式連線至 MCP 伺服器之前，請先確認您的 MCP 用戶端是否支援 streamable http 傳輸。

注意：此傳輸支援 OAuth 2.1 授權。請參閱 OAuth 2.1 Authorization。若未設定 OAuth，HTTP 端點將不會進行驗證。

使用方式

依預設，MCP 伺服器會在連接埠 8000 上執行，但可使用 --port 或 CB_MCP_PORT 環境變數進行設定。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

伺服器將在 http://localhost:8000/mcp 上提供服務。這可用於支援 streamable http 傳輸模式的 MCP 用戶端，例如 Cursor。

MCP 用戶端設定

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

SSE 傳輸模式

也可以選擇以 Server-Sent Events (SSE) 傳輸模式執行 MCP 伺服器。

注意：SSE 模式已被 MCP 棄用。我們支援 Streamable HTTP。

SSE：使用方式

依預設，MCP 伺服器會在連接埠 8000 上執行，但可使用 --port 或 CB_MCP_PORT 環境變數進行設定。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

伺服器將在 http://localhost:8000/sse 上提供服務。這可用於支援 SSE 傳輸模式的 MCP 用戶端，例如 Cursor。

SSE：MCP 用戶端設定

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

OAuth 2.1 授權

使用 --transport=http 執行時，MCP 伺服器可作為 OAuth 2.1 資源伺服器：它會根據您的身分提供者的 JWKS 驗證傳入的 bearer JWT。它與提供者無關（任何發布 JWKS 的 OAuth 2.1 / OIDC 提供者，例如 Auth0、Okta、Keycloak、AWS Cognito、Microsoft Entra 等），且不會簽發權杖或管理使用者。OAuth 設定在 stdio 上會被忽略。

OAuth 使用 Additional Configuration 中列出的 CB_MCP_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 Protected Resource Metadata，讓支援 PRM 的用戶端可以探索授權伺服器。
• 存取權限由從權杖的 scope/scp 宣告中讀取的兩個範圍控制：couchbase-mcp:read（讀取工具，包括 SQL++）和 couchbase-mcp:write（寫入工具：KV 變更、scope/collection 管理和索引管理）。完整存取需要兩者兼具。如果您的 IdP 無法發出這些標準標籤，請使用 CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL 覆寫。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

如需完整詳細資訊，請參閱文件。

Docker 映像

MCP 伺服器也可以建置並作為 Docker 容器執行。預先建置的映像可在 DockerHub 上找到，或透過 docker pull docker.io/couchbase/mcp-server:latest 提取。

此外，我們也是 Docker MCP Catalog 的一部分。

建置映像

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

執行

MCP 伺服器可以使用環境變數來設定 Couchbase 設定。環境變數與 Additional Configuration section 中所述相同。

獨立 Docker 容器

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

CB_MCP_PORT 和 CB_MCP_HOST 環境變數僅適用於 http 和 sse 等 HTTP 傳輸模式。

Docker：MCP 用戶端設定

Docker 映像可以在 stdio 傳輸模式中使用，並搭配以下設定。

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

注意事項

• couchbase_connection_string 的值取決於 Couchbase 伺服器是執行在同一台主機、另一個 Docker 容器中，還是遠端主機上。如果您的 Couchbase 伺服器執行在主機上，您的連線字串可能會是 couchbase://host.docker.internal 的形式。如需詳細資訊，請參閱 docker documentation。
• 您可以使用 --network=<your_network> 選項指定容器的網路。您選擇的網路取決於您的環境；預設為 bridge。如需詳細資訊，請參閱 network drivers in docker。

與 LLM 相關的風險

• 使用大型語言模型和類似技術涉及風險，包括可能產生不準確或有害的輸出。
• Couchbase 不會審查或評估此類輸出的品質或準確性，且此類輸出可能不代表 Couchbase 的觀點。
• 您需自行負責決定是否使用大型語言模型和相關技術，並遵守任何授權條款、使用條款，以及您組織管理您使用此類技術的政策。

使用資料收集

本產品會自動收集使用和效能資料（例如產品名稱和版本）以及瀏覽器資訊（例如 IP 位址）（統稱「使用資料」）。Couchbase 會使用使用資料，以及您可能提供給 Couchbase 的其他資料（例如您的使用者名稱或電子郵件地址），來開發和改善我們的產品，並為我們的銷售和行銷計畫提供資訊。我們不會存取或收集您儲存在 Couchbase 產品中的任何資料。我們使用使用資料來了解整體使用模式，並讓我們的產品對您更有用。如需更多關於 Couchbase 如何收集、保護和處理資訊的詳細資訊，請參閱可在 https://www.couchbase.com/privacy-policy. 檢視的 Couchbase Privacy Policy

疑難排解提示

• 如果從原始碼執行，請確保設定中的 MCP 伺服器儲存庫路徑正確。
• 請確認您的 Couchbase 連線字串、資料庫使用者名稱、密碼或憑證路徑正確。
• 如果使用 Couchbase Capella，請確保叢集可從執行 MCP 伺服器的機器存取。
• 檢查資料庫使用者是否具有至少一個 bucket 的適當存取權限。
• 確認 uv 套件管理員已正確安裝且可存取。您可能需要在設定的 command 欄位中提供 uv/uvx 的絕對路徑。
• 檢查日誌中是否有任何錯誤或警告，這些可能表示 MCP 伺服器有問題。日誌的位置取決於您的 MCP 用戶端。
• 如果您在更新本機 MCP 伺服器儲存庫後，從原始碼執行 MCP 伺服器時遇到問題，請嘗試執行 uv sync 以更新相依項目。

整合測試

我們提供高階的 MCP 整合測試，以驗證伺服器是否公開預期的工具，並可針對示範用的 Couchbase 叢集進行呼叫。

1. 匯出示範叢集憑證：
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • 選用：CB_MCP_TEST_BUCKET（測試期間要探查的 bucket）
2. 執行測試：

uv run pytest tests/ -v

👩‍💻 貢獻

我們歡迎來自社群的貢獻！無論您是要修正錯誤、新增功能或改善文件，我們都非常感謝您的協助。

如果您需要協助、發現錯誤，或想貢獻改進，最好的地方就是這裡——透過開啟 GitHub issue。

給開發者

如果您有興趣貢獻程式碼或設定開發環境：

📖 請參閱 CONTRIBUTING.md 以取得完整的開發者設定說明，包括：

• 使用 uv 進行開發環境設定
• 使用 Ruff 進行程式碼 lint 與格式化
• 安裝 pre-commit hooks
• 專案結構概覽
• 開發工作流程與實務

貢獻者快速入門

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 支援政策

我們非常感謝您對本專案的興趣！ 本專案為 Couchbase 社群維護，這表示它不受我們的支援團隊正式支援。不過，我們的工程師會積極監控並維護此儲存庫，並會盡力解決問題。

我們的支援入口網站無法協助與此專案相關的要求，因此我們懇請所有詢問都留在 GitHub 內。

您的合作讓我們能一起前進——謝謝！