Couchbase

Máy chủ Couchbase MCP

Máy chủ Couchbase MCP là một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) tự lưu trữ, kết nối các tác nhân AI và trợ lý hỗ trợ LLM — Claude, Cursor, Windsurf, VS Code Copilot và các máy khách MCP khác — với dữ liệu trong các cụm Couchbase, dù được lưu trữ trên Capella hay tự quản lý. MCP là một tiêu chuẩn mở cho phép trợ lý AI gọi các công cụ và truy vấn các nguồn dữ liệu bên ngoài; máy chủ này triển khai tiêu chuẩn đó cho Couchbase, để tác nhân AI có thể kiểm tra cụm của bạn, chạy truy vấn SQL++, đọc và ghi tài liệu, cũng như phân tích hiệu suất truy vấn bằng ngôn ngữ tự nhiên thay vì mã viết tay.

Máy chủ cung cấp các công cụ thuộc nhiều danh mục bao gồm Sức khỏe Cụm, Lược đồ Dữ liệu, Khóa-Giá trị, Truy vấn và Hiệu suất — với các kiểm soát an toàn thông qua chế độ chỉ đọc (bật theo mặc định) và tinh chỉnh vô hiệu hóa công cụ, để bạn có thể cho phép tác nhân AI khám phá và truy vấn dữ liệu của mình mà không gây rủi ro ghi không mong muốn. Máy chủ hỗ trợ cả hai phương thức truyền tải STDIO và HTTP có thể truyền phát.

Máy chủ Couchbase MCP được phân phối dưới dạng gói Chỉ mục Gói Python (PyPI) và qua Docker. Hỗ trợ doanh nghiệp cho Máy chủ Couchbase MCP có sẵn thông qua cấp phép Couchbase AI Data Plane, cũng bao gồm quyền sử dụng và hỗ trợ doanh nghiệp cho Couchbase Agent Memory và Couchbase Agent Catalog.

Để có tài liệu đầy đủ, hãy truy cập mcp-server.couchbase.com.

Để có tài liệu đầy đủ, hãy truy cập docs.couchbase.com/mcp-server.

Mục lục

• Tại sao nên dùng Máy chủ Couchbase MCP
• Ví dụ về Lời nhắc
• Tính năng/Công cụ
• Điều kiện tiên quyết
• Cấu hình
• Máy chủ Thông tin Chi tiết Vận hành
• Chế độ Truyền tải HTTP có thể truyền phát
• Chế độ Truyền tải SSE
• Ủy quyền OAuth 2.1
• Hình ảnh Docker
• Thu thập Dữ liệu Sử dụng
• Mẹo Khắc phục Sự cố
• Kiểm thử Tích hợp
• Câu hỏi thường gặp
• Đóng góp
• Chính sách Hỗ trợ

Tại sao nên dùng Máy chủ Couchbase MCP

• An toàn theo mặc định — các thao tác ghi (upsert/chèn/xóa tài liệu và truy vấn SQL++ sửa đổi dữ liệu) bị chặn trừ khi bạn đặt rõ ràng CB_MCP_READ_ONLY_MODE=false, và các công cụ riêng lẻ có thể bị vô hiệu hóa hoặc chặn sau xác nhận của người dùng.
• Hoạt động với Capella và cụm tự quản lý — cùng một cấu hình kết nối với Couchbase Capella (được quản lý đầy đủ) hoặc cụm Máy chủ Couchbase tự lưu trữ.
• Nhận biết RBAC — vô hiệu hóa công cụ là một lớp tiện lợi để hướng dẫn hành vi LLM; kiểm soát truy cập dựa trên vai trò của người dùng Couchbase cơ bản vẫn là ranh giới bảo mật có thẩm quyền.
• Truyền tải sản xuất — chạy qua STDIO cho máy khách máy tính để bàn cục bộ, hoặc HTTP có thể truyền phát với OAuth 2.1 tùy chọn (JWT/JWKS, không phụ thuộc nhà cung cấp — Auth0, Okta, Keycloak, Entra, Cognito, v.v.) cho triển khai dùng chung/từ xa.
• Bất kỳ máy khách MCP nào — đã kiểm thử với Claude Desktop, Cursor, Windsurf, VS Code và JetBrains AI Assistant/Junie; hoạt động với bất kỳ máy khách nào triển khai đặc tả MCP.

Ví dụ về Lời nhắc

Khi máy chủ đã được kết nối, bạn có thể trò chuyện với cụm Couchbase của mình bằng ngôn ngữ tự nhiên thông qua trợ lý AI. Ví dụ:

• "Tôi có những bucket, scope và collection nào trong cụm này, và lược đồ của collection orders là gì?"
• "Chạy truy vấn SQL++ để tìm 10 tài liệu gần đây nhất trong collection users where status = 'active'."
• "5 truy vấn chậm nhất trên cụm này trong giờ qua là gì, và có truy vấn nào thiếu chỉ mục bao phủ không?"
• "Kiểm tra xem cụm này có khỏe mạnh không và cho tôi biết dịch vụ nào đang chạy."
• "Chèn một tài liệu mới vào collection products với các trường sau: ..." (yêu cầu CB_MCP_READ_ONLY_MODE=false)

Tính năng/Công cụ

Bản phân phối này cung cấp hai máy chủ: máy chủ vận hành (mặc định — các bảng ngay dưới đây) kết nối với cụm Couchbase thông thường qua SDK couchbase, và máy chủ Thông tin Chi tiết Vận hành (bảng riêng ở phần dưới) kết nối với cụm Thông tin Chi tiết Vận hành qua SDK couchbase-operational-insights.

Công cụ thiết lập và sức khỏe cụm

Công cụ khám phá mô hình dữ liệu và lược đồ

Công cụ thao tác KV tài liệu

Công cụ truy vấn và lập chỉ mục

Công cụ tìm kiếm toàn văn (FTS)

Yêu cầu Máy chủ Couchbase 7.6+ và dịch vụ Search. Tìm kiếm vector không được hỗ trợ bởi các công cụ này (xem bộ công cụ tìm kiếm vector riêng).

Công cụ phân tích hiệu suất truy vấn

Công cụ Thông tin Chi tiết Vận hành

Được đăng ký bởi máy chủ operational-insights riêng (xem Máy chủ Thông tin Chi tiết Vận hành bên dưới), không phải máy chủ operational mặc định.

Các công cụ Server Async Request API tạo thành một luồng bắt đầu → thăm dò → loại bỏ hoặc hủy cho các truy vấn chạy lâu: run_query_async trả về một query_handle, get_async_query_results được thăm dò cho đến khi báo cáo sẵn sàng (và trả về các hàng), sau đó discard_async_query_results giải phóng kết quả hoặc, đối với một truy vấn vẫn đang chạy, cancel_async_query dừng nó.

Lưu ý: get_collections_in_scope, get_schema_for_collection, create_index và list_indexes tồn tại, với hành vi khác nhau, trên cả hai máy chủ. (get_server_configuration_status cũng xuất hiện trên cả hai, nhưng nó được cố ý là một công cụ dùng chung — cùng triển khai, cùng định dạng kết quả — vì vậy không cần phân biệt.) Mỗi máy chủ là một tiến trình riêng biệt, vì vậy điều này chỉ là mối quan tâm nếu một máy khách MCP duy nhất đăng ký cả operational và operational-insights đồng thời — trong trường hợp đó, hãy phân biệt ở lớp cấu hình máy khách (ví dụ: bằng cách đặt tên khác nhau cho hai mục máy chủ trong cấu hình của chính máy khách).

Điều kiện tiên quyết

• Python 3.10 trở lên.
• Một cụm Couchbase đang chạy. Cách dễ nhất để bắt đầu là sử dụng bậc miễn phí Capella, phiên bản được quản lý đầy đủ của máy chủ Couchbase. Bạn có thể làm theo hướng dẫn để nhập một trong các tập dữ liệu mẫu hoặc nhập dữ liệu của riêng bạn.
• uv được cài đặt để chạy máy chủ.
• Một máy khách MCP như Claude Desktop được cài đặt để kết nối máy chủ với Claude. Hướng dẫn được cung cấp cho Claude Desktop và Cursor. Các máy khách MCP khác cũng có thể được sử dụng.

Cấu hình

Máy chủ MCP có thể được chạy từ gói PyPI được xây dựng sẵn hoặc từ mã nguồn bằng uv.

Chạy từ PyPI

Chúng tôi xuất bản một gói PyPI được xây dựng sẵn cho máy chủ MCP.

Cấu hình máy chủ bằng gói được xây dựng sẵn cho máy khách MCP

Xác thực cơ bản

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

hoặc

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"
      }
    }
  }
}

Lưu ý: Nếu bạn có các máy chủ MCP khác đang sử dụng trong máy khách, bạn có thể thêm nó vào đối tượng mcpServers hiện có.

Chạy từ mã nguồn

Máy chủ MCP có thể được chạy từ mã nguồn bằng kho lưu trữ này.

Sao chép kho lưu trữ vào máy cục bộ của bạn

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

Cấu hình máy chủ bằng mã nguồn cho máy khách MCP

Đây là cấu hình phổ biến cho các máy khách MCP như 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"
      }
    }
  }
}

Lưu ý: path/to/cloned/repo/mcp-server-couchbase/ phải là đường dẫn đến kho lưu trữ đã sao chép trên máy cục bộ của bạn. Đừng quên dấu gạch chéo ở cuối!

Lưu ý: Nếu bạn có các máy chủ MCP khác đang sử dụng trong máy khách, bạn có thể thêm nó vào đối tượng mcpServers hiện có.

Cấu hình bổ sung cho máy chủ MCP

Máy chủ có thể được cấu hình bằng các biến môi trường hoặc đối số dòng lệnh:

Cấu hình chế độ chỉ đọc

CB_MCP_READ_ONLY_MODE là công tắc duy nhất kiểm soát các thao tác ghi:

• Khi true (mặc định): Tất cả các thao tác ghi (KV, Query, quản lý scope/collection và quản lý index) bị vô hiệu hóa. Tất cả các công cụ ghi (KV: upsert, insert, replace, delete, sub-document mutate; quản lý scope/collection: create_scope, create_collection, delete_scope, delete_collection; quản lý index: create_index, build_index, drop_index) không được tải và sẽ không khả dụng cho LLM, và các truy vấn SQL++ sửa đổi dữ liệu hoặc cấu trúc bị chặn.
• Khi false: Tất cả các công cụ ghi được tải và các truy vấn sửa đổi dữ liệu/cấu trúc SQL++ được phép.

Đây là mặc định an toàn được khuyến nghị để ngăn chặn việc sửa đổi dữ liệu ngoài ý muốn bởi LLM.

Lưu ý: Để xác thực, bạn cần Tên người dùng và Mật khẩu hoặc đường dẫn Chứng chỉ máy khách và Khóa. Tùy chọn, bạn có thể chỉ định đường dẫn chứng chỉ gốc CA sẽ được sử dụng để xác thực chứng chỉ máy chủ. Nếu cả đường dẫn Chứng chỉ máy khách & Khóa và tên người dùng và mật khẩu được chỉ định, chứng chỉ máy khách sẽ được sử dụng để xác thực.

Vô hiệu hóa công cụ

Bạn có thể vô hiệu hóa các công cụ cụ thể để ngăn chúng được tải và hiển thị cho MCP client. Các công cụ bị vô hiệu hóa sẽ không xuất hiện trong quá trình khám phá công cụ và không thể được LLM gọi.

Các định dạng được hỗ trợ

Danh sách phân tách bằng dấu phẩy:

# 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

Đường dẫn tệp (một tên công cụ trên mỗi dòng):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Định dạng tệp (ví dụ: disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Các dòng bắt đầu bằng # được coi là chú thích và bị bỏ qua.

Ví dụ cấu hình MCP client

Sử dụng danh sách phân tách bằng dấu phẩy:

{
  "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"
      }
    }
  }
}

Sử dụng đường dẫn tệp (khuyến nghị cho nhiều công cụ):

{
  "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"
      }
    }
  }
}

Lưu ý bảo mật quan trọng

Cảnh báo: Chỉ vô hiệu hóa các công cụ không đảm bảo rằng một số thao tác nhất định không thể được thực hiện. Quyền RBAC (Kiểm soát truy cập dựa trên vai trò) của người dùng cơ sở dữ liệu bên dưới là biện pháp kiểm soát bảo mật có thẩm quyền.

Ví dụ: ngay cả khi bạn vô hiệu hóa upsert_document_by_id và delete_document_by_id, việc sửa đổi dữ liệu vẫn có thể xảy ra thông qua công cụ run_sql_plus_plus_query sử dụng các câu lệnh DML SQL++ (INSERT, UPDATE, DELETE, MERGE) trừ khi:

• CB_MCP_READ_ONLY_MODE được đặt thành true (mặc định), HOẶC
• Người dùng cơ sở dữ liệu thiếu các quyền RBAC cần thiết để sửa đổi dữ liệu

Thực tiễn tốt nhất: Luôn cấu hình các quyền RBAC phù hợp trên thông tin xác thực người dùng Couchbase của bạn như là biện pháp bảo mật chính. Sử dụng việc vô hiệu hóa công cụ như một lớp bổ sung để hướng dẫn hành vi của LLM và giảm bề mặt tấn công, không phải là biện pháp kiểm soát bảo mật duy nhất.

Yêu cầu/Xác nhận cho các lệnh gọi công cụ

Bạn có thể yêu cầu xác nhận rõ ràng từ người dùng cho các công cụ cụ thể trước khi thực thi (khi MCP client hỗ trợ elicitation).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools hỗ trợ các định dạng sau:

• Danh sách phân tách bằng dấu phẩy
• Đường dẫn tệp (một tên công cụ trên mỗi dòng, hỗ trợ chú thích #)

Ví dụ:

# 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

Khi một công cụ được liệt kê được gọi:

• Nếu client hỗ trợ elicitation, người dùng sẽ được nhắc xác nhận.
• Nếu client không hỗ trợ elicitation, công cụ sẽ thực thi mà không cần xác nhận để tương thích ngược.

Bạn cũng có thể kiểm tra phiên bản của máy chủ bằng cách sử dụng:

uvx couchbase-mcp-server --version

Ghi nhật ký

Máy chủ MCP ghi nhật ký vào stderr theo mặc định. Ghi nhật ký được cấu hình với các biến CB_MCP_LOG_* được liệt kê trong Cấu hình bổ sung:

• CB_MCP_LOG_LEVEL — mức độ ghi nhật ký: info (mặc định) ghi lại các sự kiện vòng đời và lệnh gọi công cụ, debug thêm chi tiết nội bộ chi tiết, và off vô hiệu hóa tất cả ghi nhật ký.
• CB_MCP_LOG_SINKS — nơi nhật ký được ghi: stderr (mặc định), các tệp xoay vòng theo cấp độ (file), hoặc cả hai. Với file, một tệp được ghi cho mỗi cấp độ (ví dụ mcp_server.info.log và mcp_server.error.log) tại đường dẫn được đặt bởi CB_MCP_LOG_FILE.
• Kích thước xoay vòng — CB_MCP_LOG_ROTATION_MAX_SIZE_MB là kích thước toàn cục (tính bằng MB) tại đó mỗi tệp theo cấp độ xoay vòng. Ghi đè các cấp độ riêng lẻ bằng CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), cũng tính bằng MB, kế thừa giá trị toàn cục khi không được đặt. Kích thước 0 (toàn cục hoặc theo cấp độ) không hợp lệ và sẽ quay về mặc định (1 MB) với cảnh báo khi khởi động. CB_MCP_LOG_MAX_BYTES (byte) không được dùng nữa nhưng vẫn được tôn trọng để tương thích ngược; nó bị bỏ qua khi CB_MCP_LOG_ROTATION_MAX_SIZE_MB cũng được đặt và in cảnh báo không dùng nữa khi khởi động.
• Lưu giữ — CB_MCP_LOG_RETENTION_BACKUP_COUNT đặt số lượng bản sao lưu xoay vòng được giữ cho mỗi cấp độ (không bao gồm tệp trực tiếp); mặc định là 1 bảo toàn hành vi trước đó. Ghi đè các cấp độ riêng lẻ bằng CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), kế thừa giá trị toàn cục khi không được đặt. Đặt số lượng thành 0 để chỉ giữ tệp trực tiếp cho cấp độ đó — nó vẫn bị giới hạn bởi kích thước xoay vòng (được đặt lại khi xoay vòng thay vì sao lưu).
• Ảnh chụp nhanh cấu hình máy chủ — khi sink file hoạt động, một bản ghi một lần (HĐH, Python, phiên bản phụ thuộc, giao thức truyền tải, cấu hình ghi nhật ký đã giải quyết và cấu hình máy chủ đã được biên tập) được ghi dưới dạng JSON vào một tệp mcp_server_config.log.json chuyên dụng (được suy ra từ cơ sở CB_MCP_LOG_FILE). Nó bị ghi đè mỗi lần khởi động, vì vậy bộ phận hỗ trợ luôn có cấu hình hiện tại và nó không bao giờ bị cuộn ra khỏi nhật ký xoay vòng.

# 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

Để biết thêm chi tiết, hãy xem tài liệu.

Cấu hình cụ thể cho client

Máy chủ Operational Insights

Cùng với máy chủ operational mặc định (máy chủ mà mọi phần ở trên mô tả), bản phân phối này đi kèm với một máy chủ thứ hai cho các cụm Operational Insights, sử dụng SDK couchbase-operational-insights riêng biệt. Đây là một sản phẩm khác với cụm Couchbase thông thường và chạy như một quy trình độc lập trên cổng riêng của nó.

Chạy nó bằng cách truyền operational-insights làm lệnh con CLI (hoặc thêm nó làm lệnh của container):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string là một URL HTTP(S), không phải chuỗi kết nối couchbase:// — ví dụ: http://localhost:8095 cho một máy chủ Operational Insights cục bộ, hoặc https://<host>:18095 cho Capella. Đây là sai lầm cấu hình phổ biến nhất khi trỏ máy chủ này vào một cụm.

Mọi cờ khác (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) giống hệt với máy chủ vận hành — xem Cấu hình bổ sung cho MCP Server — ngoại trừ mặc định cho cổng (8001, không phải 8000) và tệp nhật ký (mcp_server_operational_insights.log, không phải mcp_server.log), vì hai máy chủ không thể chia sẻ cả hai. OAuth sử dụng cùng nhãn phạm vi (couchbase-mcp:read / couchbase-mcp:write) như máy chủ vận hành, vì vậy cấu hình IdP hiện có hoạt động cho cả hai mà không cần thay đổi.

Ví dụ cấu hình máy khách MCP:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

Xem Công cụ Operational Insights ở trên để biết danh sách công cụ và lưu ý về ba tên công cụ dùng chung với máy chủ vận hành.

Cả hai máy chủ chia sẻ một mục MCP Registry duy nhất, io.github.couchbase/mcp-server-couchbase, được xuất bản từ server.json. Mục này có mục gói riêng cho từng máy chủ (PyPI và Docker). Mỗi mục truyền lệnh con của nó (operational hoặc operational-insights) và chỉ khai báo các đối số và biến môi trường của máy chủ đó.

Chế độ Truyền tải HTTP Streamable

MCP Server có thể chạy ở chế độ truyền tải Streamable HTTP, cho phép nhiều máy khách kết nối đến cùng một phiên bản máy chủ qua HTTP. Kiểm tra xem máy khách MCP của bạn có hỗ trợ truyền tải streamable http trước khi cố gắng kết nối đến máy chủ MCP ở chế độ này.

Lưu ý: Ủy quyền OAuth 2.1 được hỗ trợ trên truyền tải này. Xem Ủy quyền OAuth 2.1. Nếu không cấu hình OAuth, điểm cuối HTTP không được xác thực.

Cách sử dụng

Theo mặc định, máy chủ MCP sẽ chạy trên cổng 8000 nhưng có thể cấu hình bằng biến môi trường --port hoặc CB_MCP_PORT.

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

Máy chủ sẽ khả dụng tại http://localhost:8000/mcp. Điều này có thể được sử dụng trong các máy khách MCP hỗ trợ chế độ truyền tải streamable http như Cursor.

Cấu hình máy khách MCP

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

Chế độ Truyền tải SSE

Có tùy chọn chạy máy chủ MCP ở chế độ truyền tải Server-Sent Events (SSE).

Lưu ý: Chế độ SSE đã bị không dùng nữa bởi MCP. Chúng tôi hỗ trợ Streamable HTTP.

SSE: Cách sử dụng

Theo mặc định, máy chủ MCP sẽ chạy trên cổng 8000 nhưng có thể cấu hình bằng biến môi trường --port hoặc CB_MCP_PORT.

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

Máy chủ sẽ khả dụng tại http://localhost:8000/sse. Điều này có thể được sử dụng trong các máy khách MCP hỗ trợ chế độ truyền tải SSE như Cursor.

SSE: Cấu hình máy khách MCP

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

Ủy quyền OAuth 2.1

Khi chạy với --transport=http, máy chủ MCP có thể hoạt động như một máy chủ tài nguyên OAuth 2.1: nó xác thực các JWT bearer đến dựa trên JWKS của nhà cung cấp danh tính của bạn. Nó không phụ thuộc vào nhà cung cấp (bất kỳ nhà cung cấp OAuth 2.1 / OIDC nào xuất bản JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, v.v.) và không phát hành mã thông báo hoặc quản lý người dùng. Cài đặt OAuth bị bỏ qua trên stdio.

OAuth được cấu hình với các biến CB_MCP_OAUTH_* được liệt kê trong Cấu hình bổ sung:

• OAuth chỉ kích hoạt khi cả ba biến CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER và CB_MCP_OAUTH_JWT_AUDIENCE được đặt; chỉ đặt một số trong số chúng sẽ gây lỗi khi khởi động.
• Đặt CB_MCP_OAUTH_MCP_BASE_URL bổ sung xuất bản Siêu dữ liệu Tài nguyên được Bảo vệ RFC 9728 để các máy khách nhận biết PRM có thể khám phá máy chủ ủy quyền.
• Quyền truy cập được kiểm soát bởi hai phạm vi đọc từ xác nhận quyền scope/scp của mã thông báo: couchbase-mcp:read (công cụ đọc, bao gồm SQL++) và couchbase-mcp:write (công cụ ghi: thay đổi KV, quản lý phạm vi/bộ sưu tập và quản lý chỉ mục). Quyền truy cập đầy đủ yêu cầu cả hai. Nếu IdP của bạn không thể phát ra các nhãn chuẩn đó, hãy ghi đè chúng bằng 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>'

Để biết chi tiết đầy đủ, xem tài liệu.

Hình ảnh Docker

Máy chủ MCP cũng có thể được xây dựng và chạy như một container Docker. Hình ảnh được xây dựng sẵn có thể được tìm thấy trên DockerHub hoặc kéo qua docker pull docker.io/couchbase/mcp-server:latest.

Ngoài ra, chúng tôi là một phần của Docker MCP Catalog.

Xây dựng hình ảnh

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

Chạy

Máy chủ MCP có thể được chạy với các biến môi trường được sử dụng để cấu hình cài đặt Couchbase. Các biến môi trường giống như được mô tả trong phần Cấu hình bổ sung.

Container Docker độc lập

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

Các biến môi trường CB_MCP_PORT và CB_MCP_HOST chỉ áp dụng trong trường hợp các chế độ truyền tải HTTP như http và sse.

Docker: Cấu hình máy khách MCP

Hình ảnh Docker có thể được sử dụng ở chế độ truyền tải stdio với cấu hình sau.

{
  "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"
      ]
    }
  }
}

Ghi chú

• Giá trị couchbase_connection_string phụ thuộc vào việc máy chủ Couchbase đang chạy trên cùng máy chủ, trong một container Docker khác hay trên máy chủ từ xa. Nếu máy chủ Couchbase của bạn đang chạy trên máy chủ của bạn, chuỗi kết nối của bạn có thể có dạng couchbase://host.docker.internal. Để biết chi tiết, tham khảo tài liệu docker.
• Bạn có thể chỉ định mạng của container bằng tùy chọn --network=<your_network>. Mạng bạn chọn phụ thuộc vào môi trường của bạn; mặc định là bridge. Để biết chi tiết, tham khảo trình điều khiển mạng trong docker.

Rủi ro liên quan đến LLM

• Việc sử dụng các mô hình ngôn ngữ lớn và công nghệ tương tự liên quan đến rủi ro, bao gồm khả năng tạo ra đầu ra không chính xác hoặc có hại.
• Couchbase không xem xét hoặc đánh giá chất lượng hoặc độ chính xác của các đầu ra đó và các đầu ra đó có thể không phản ánh quan điểm của Couchbase.
• Bạn hoàn toàn chịu trách nhiệm quyết định có sử dụng các mô hình ngôn ngữ lớn và công nghệ liên quan hay không, cũng như tuân thủ mọi điều khoản giấy phép, điều khoản sử dụng và chính sách của tổ chức bạn quản lý việc sử dụng chúng.

Thu thập Dữ liệu Sử dụng

Sản phẩm này tự động thu thập dữ liệu sử dụng và hiệu suất (như tên sản phẩm và phiên bản) và thông tin trình duyệt (như địa chỉ IP) (gọi chung là "Dữ liệu Sử dụng"). Couchbase sử dụng Dữ liệu Sử dụng, cùng với dữ liệu khác bạn có thể cung cấp cho Couchbase (như tên người dùng hoặc địa chỉ email của bạn), để phát triển và cải thiện sản phẩm của chúng tôi cũng như cung cấp thông tin cho các chương trình bán hàng và tiếp thị của chúng tôi. Chúng tôi không truy cập hoặc thu thập bất kỳ dữ liệu nào bạn lưu trữ trong các sản phẩm Couchbase. Chúng tôi sử dụng Dữ liệu Sử dụng để hiểu các mẫu sử dụng tổng hợp và làm cho sản phẩm của chúng tôi hữu ích hơn cho bạn. Để biết thêm thông tin về cách Couchbase thu thập, bảo vệ và xử lý thông tin, vui lòng tham khảo Chính sách Quyền riêng tư của Couchbase có thể xem tại https://www.couchbase.com/privacy-policy.

Mẹo khắc phục sự cố

• Đảm bảo đường dẫn đến kho lưu trữ máy chủ MCP của bạn là chính xác trong cấu hình nếu chạy từ mã nguồn.
• Xác minh rằng chuỗi kết nối Couchbase, tên người dùng cơ sở dữ liệu, mật khẩu hoặc đường dẫn đến chứng chỉ của bạn là chính xác.
• Nếu sử dụng Couchbase Capella, hãy đảm bảo rằng cụm có thể truy cập từ máy nơi máy chủ MCP đang chạy.
• Kiểm tra rằng người dùng cơ sở dữ liệu có quyền thích hợp để truy cập ít nhất một bucket.
• Xác nhận rằng trình quản lý gói uv được cài đặt đúng cách và có thể truy cập. Bạn có thể cần cung cấp đường dẫn tuyệt đối đến uv/uvx trong trường command trong cấu hình.
• Kiểm tra nhật ký để tìm bất kỳ lỗi hoặc cảnh báo nào có thể chỉ ra sự cố với máy chủ MCP. Vị trí của nhật ký phụ thuộc vào máy khách MCP của bạn.
• Nếu bạn gặp sự cố khi chạy máy chủ MCP từ mã nguồn sau khi cập nhật kho lưu trữ máy chủ MCP cục bộ, hãy thử chạy uv sync để cập nhật các phụ thuộc.

Kiểm thử tích hợp

Chúng tôi cung cấp các bài kiểm thử tích hợp MCP cấp cao để xác minh rằng máy chủ hiển thị các công cụ dự kiến và chúng có thể được gọi với một cụm Couchbase demo.

1. Xuất thông tin xác thực cụm demo:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Tùy chọn: CB_MCP_TEST_BUCKET (một bucket để thăm dò trong các bài kiểm thử)
   • Tùy chọn, cho các bài kiểm thử riêng của máy chủ Operational Insights: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Các bài kiểm thử đó tự động bỏ qua (không thất bại) khi không được đặt.
2. Chạy các bài kiểm thử:

uv run --extra dev pytest tests/integration -v

Câu hỏi thường gặp

Máy chủ Couchbase MCP là gì? Đây là một triển khai tự lưu trữ của Model Context Protocol cho phép các trợ lý AI và tác nhân (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie và bất kỳ máy khách MCP nào khác) truy vấn và tùy chọn, sửa đổi dữ liệu trong một cụm Couchbase bằng ngôn ngữ tự nhiên.

Làm cách nào để kết nối Claude Desktop với Couchbase? Cài đặt máy chủ bằng uvx couchbase-mcp-server (hoặc chạy từ mã nguồn hoặc Docker), sau đó thêm cấu hình của nó vào claude_desktop_config.json của Claude Desktop như được hiển thị trong Cấu hình. Khởi động lại Claude Desktop và nó sẽ nhận các công cụ mới.

Tôi có thể sử dụng điều này với Couchbase Capella không? Có. Cấu hình CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (hoặc chứng chỉ mTLS) tương tự hoạt động cho cả cụm Couchbase Capella và Couchbase Server tự quản lý.

Có an toàn để cho một tác nhân AI ghi vào cơ sở dữ liệu của tôi không? Theo mặc định, CB_MCP_READ_ONLY_MODE là true, vì vậy tất cả các thao tác ghi — upsert/chèn/thay thế/xóa tài liệu và các câu lệnh SQL++ sửa đổi dữ liệu — bị vô hiệu hóa và các công cụ ghi thậm chí không được tải. Bạn cũng có thể vô hiệu hóa các công cụ riêng lẻ (xem Vô hiệu hóa Công cụ) hoặc yêu cầu xác nhận rõ ràng từ người dùng trước khi các công cụ cụ thể chạy (xem Elicitation/Confirmation). Các kiểm soát cấp công cụ hướng dẫn hành vi LLM; quyền RBAC của người dùng Couchbase của bạn vẫn là ranh giới bảo mật thực sự.

Tôi có thể chạy các truy vấn ngôn ngữ tự nhiên trên dữ liệu của mình mà không cần tự viết SQL++ không? Có — hãy hỏi trợ lý AI của bạn một câu hỏi bằng tiếng Anh đơn giản (ví dụ: "hiển thị cho tôi 10 đơn hàng gần nhất trên $100") và nó có thể dịch điều đó thành một truy vấn SQL++ bằng công cụ run_sql_plus_plus_query. Bạn cũng có thể yêu cầu trợ lý explain_sql_plus_plus_query một truy vấn hoặc hỏi cố vấn chỉ mục để được khuyến nghị. Sự khác biệt giữa transport STDIO, Streamable HTTP và SSE là gì? STDIO dành cho một MCP client cục bộ duy nhất (ví dụ: Claude Desktop) khởi chạy server như một tiến trình con. Streamable HTTP cho phép nhiều client chia sẻ một instance server đang chạy qua HTTP và hỗ trợ OAuth 2.1. SSE là transport HTTP cũ hơn, hiện đã bị spec MCP không dùng nữa để chuyển sang Streamable HTTP — xem Streamable HTTP Transport Mode.

Điều này có được Couchbase hỗ trợ chính thức không? Dự án này được cộng đồng Couchbase duy trì — xem Support Policy. Hỗ trợ doanh nghiệp có sẵn riêng qua Couchbase AI Data Plane.

Đóng góp

Chúng tôi hoan nghênh mọi đóng góp từ cộng đồng! Dù bạn muốn sửa lỗi, thêm tính năng hay cải thiện tài liệu, sự giúp đỡ của bạn đều được trân trọng.

Nếu bạn cần trợ giúp, phát hiện lỗi hoặc muốn đóng góp cải tiến, nơi tốt nhất để làm điều đó chính là tại đây — bằng cách mở một issue trên GitHub.

Dành cho nhà phát triển

Nếu bạn quan tâm đến việc đóng góp mã nguồn hoặc thiết lập môi trường phát triển:

📖 Xem CONTRIBUTING.md để biết hướng dẫn thiết lập nhà phát triển toàn diện, bao gồm:

• Thiết lập môi trường phát triển với uv
• Lint và định dạng mã với Ruff
• Cài đặt pre-commit hooks
• Tổng quan cấu trúc dự án
• Quy trình và thực tiễn phát triển

Bắt đầu nhanh cho người đóng góp

# 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

📢 Chính sách hỗ trợ

Chúng tôi thực sự trân trọng sự quan tâm của bạn đến dự án này! Dự án này được cộng đồng Couchbase duy trì, nghĩa là nó không được hỗ trợ chính thức bởi đội ngũ hỗ trợ của chúng tôi. Tuy nhiên, các kỹ sư của chúng tôi đang tích cực theo dõi và duy trì repo này và sẽ cố gắng giải quyết các vấn đề trên cơ sở nỗ lực tốt nhất.

Cổng hỗ trợ của chúng tôi không thể hỗ trợ các yêu cầu liên quan đến dự án này, vì vậy chúng tôi kính đề nghị mọi thắc mắc nên được giữ trong GitHub.

Sự hợp tác của bạn giúp tất cả chúng ta cùng tiến về phía trước — cảm ơn bạn!