Couchbase MCP Server

Couchbase MCP 伺服器

Couchbase MCP 伺服器是一款自託管的 MCP 伺服器，可讓 AI 代理程式連線至 Couchbase 叢集中的資料並與之互動，無論該叢集是託管於 Capella 或自行管理。它提供跨類別的工具，包括叢集健康狀態、資料結構描述、鍵值、查詢和效能——並透過唯讀模式和精細的工具停用功能來提供安全控制。它同時支援 STDIO 和可串流的 HTTP 傳輸。

Couchbase MCP 伺服器以 Python Package Index (PyPI) 套件和 Docker 形式發佈。 Couchbase MCP 伺服器的企業支援可透過授權 Couchbase AI Data Plane 取得，該授權也賦予您使用 Couchbase Agent Memory 和 Couchbase Agent Catalog 的權利以及其企業支援。

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

功能/工具

叢集設定與健康狀態工具

資料模型與結構描述探索工具

文件 KV 操作工具

查詢與索引工具

查詢效能分析工具

先決條件

• Python 3.10 或更高版本。
• 一個正在執行的 Couchbase 叢集。最簡單的入門方式是使用 Capella 免費層，它是完全託管的 Couchbase 伺服器版本。您可以按照指示匯入其中一個範例資料集或匯入您自己的資料。
• 已安裝 uv 以執行伺服器。
• 已安裝一個 MCP 客戶端，例如 Claude Desktop，以將伺服器連線至 Claude。此處提供 Claude Desktop 和 Cursor 的指示。也可以使用其他 MCP 客戶端。

設定

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

從 PyPI 執行

我們為 MCP 伺服器發佈了一個預先建置的 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 伺服器，可以將其新增至現有的 mcpServers 物件中。

從原始碼執行

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

將儲存庫複製到您的本機機器

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

針對 MCP 客戶端使用原始碼的伺服器設定

這是 MCP 客戶端（例如 Claude Desktop、Cursor、Windsurf Editor）的通用設定。

{
  "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 伺服器，可以將其新增至現有的 mcpServers 物件中。

MCP 伺服器的其他設定

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

唯讀模式設定

CB_MCP_READ_ONLY_MODE 是控制寫入操作的單一開關：

• 當 true（預設）時：所有寫入操作（KV 和查詢）都會被停用。KV 寫入工具（更新插入、插入、取代、刪除）不會載入，且 LLM 無法使用，而修改資料或結構的 SQL++ 查詢也會被封鎖。
• 當 false 時：KV 寫入工具會載入，且允許 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 行為並減少攻擊面，而非作為唯一的安全控制機制。

工具呼叫的引出/確認機制

您可以要求特定工具在執行前需經使用者明確確認（當 MCP 客戶端支援引出功能時）。

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

當叫用清單中的工具時：

• 若客戶端支援引出功能，系統會提示使用者確認。
• 若客戶端不支援引出功能，為維持回溯相容性，工具將在未經確認的情況下執行。

您也可以使用以下指令檢查伺服器版本：

uvx couchbase-mcp-server --version

記錄

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

• CB_MCP_LOG_LEVEL — 記錄的詳細程度：info（預設值）記錄生命週期事件和工具叫用，debug 會新增詳細的內部細節，而 off 則會停用所有記錄。
• CB_MCP_LOG_SINKS — 記錄的輸出位置：stderr（預設值）、按等級分割的輪替檔案（file），或兩者皆輸出。使用 file 時，會在 CB_MCP_LOG_FILE 設定的路徑下，為每個等級寫入一個檔案（例如 mcp_server.info.log 和 mcp_server.error.log）。

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

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

客戶端特定設定

可串流 HTTP 傳輸模式

MCP 伺服器可以在可串流 HTTP 傳輸模式下執行，這允許多個客戶端透過 HTTP 連線到同一個伺服器執行個體。 在嘗試以此模式連線到 MCP 伺服器之前，請檢查您的 MCP 客戶端是否支援可串流 HTTP 傳輸。

注意：此傳輸模式支援 OAuth 2.1 授權。請參閱 OAuth 2.1 授權。在未設定 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 上提供服務。這可以在支援可串流 HTTP 傳輸模式的 MCP 客戶端（例如 Cursor）中使用。

MCP 客戶端設定

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

SSE 傳輸模式

可以選擇以伺服器傳送事件 (SSE) 傳輸模式執行 MCP 伺服器。

注意：SSE 模式已被 MCP 棄用。我們已支援可串流 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 驗證傳入的承載 JWT。它與提供者無關（任何發布 JWKS 的 OAuth 2.1 / OIDC 提供者 — Auth0、Okta、Keycloak、AWS Cognito、Microsoft Entra 等），並且不會核發權杖或管理使用者。OAuth 設定在 stdio 上會被忽略。

OAuth 可透過其他設定中列出的 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 受保護資源中繼資料，以便感知 PRM 的客戶端可以探索授權伺服器。
• 存取權限由從權杖的 scope/scp 宣告中讀取的兩個範圍控制：couchbase-mcp:read（讀取工具，包括 SQL++）和 couchbase-mcp:write（KV 變更工具）。完整存取權限需要兩者兼具。

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 目錄的一部分。

建置映像檔

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 的相關組態。這些環境變數與其他組態章節中描述的相同。

獨立的 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 文件。
• 您可以使用 --network=<your_network> 選項來指定容器的網路設定。選擇的網路取決於您的環境；預設為 bridge。詳情請參閱 docker 中的網路驅動程式。

與 LLM 相關的風險

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

疑難排解提示

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

整合測試

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

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

uv run pytest tests/ -v

👩‍💻 貢獻

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

如果您需要幫助、發現錯誤或想貢獻改進，最好的方式就是在這裡——開啟 GitHub 議題。

給開發者

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

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

• 使用 uv 設定開發環境
• 使用 Ruff 進行程式碼 linting 與格式化
• 安裝 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 上。

您的協作能幫助我們一同向前邁進——謝謝您！