用于 ADK 的 Couchbase MCP 工具¶

ADK 已支持PythonTypeScript

Couchbase MCP 服务器将你的 ADK 智能体连接到 Couchbase 集群。通过此集成，你的智能体能够使用自然语言探索 Couchbase 数据，包括探索数据、运行查询以及分析性能问题。

使用场景¶

数据探索：发现 Bucket、Scope、Collection 和文档 Schema，使用自然语言进行数据查询。
数据库管理：通过对话式命令监控集群健康状况、检查运行中的服务，并管理 Bucket、Scope 和 Collection 结构。
查询性能分析：获取索引建议、分析查询计划，并调查慢查询或非选择性查询以优化性能。

先决条件¶

一个运行中的 Couchbase 集群。你可以：
- 使用 Couchbase Capella（托管云服务）
- 在本地或自托管运行 Couchbase Server 7.x+
集群的连接字符串和凭据（用户名/密码或用于 mTLS 的客户端证书）
已安装 uv 包管理器（用于 uvx 命令）

在智能体中使用¶

PythonTypeScript

本地 MCP 服务器

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

CB_CONNECTION_STRING = "couchbase://localhost"
CB_USERNAME = "Administrator"
CB_PASSWORD = "password"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="couchbase_agent",
    instruction="协助用户探索和查询 Couchbase 数据库。",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=["couchbase-mcp-server"],
                    env={
                        "CB_CONNECTION_STRING": CB_CONNECTION_STRING,
                        "CB_USERNAME": CB_USERNAME,
                        "CB_PASSWORD": CB_PASSWORD,
                        "CB_MCP_READ_ONLY_MODE": "true",  # 防止写入操作
                    },
                ),
                timeout=60,
            ),
        )
    ],
)

本地 MCP 服务器

import { LlmAgent, MCPToolset } from "@google/adk";

const CB_CONNECTION_STRING = "couchbase://localhost";
const CB_USERNAME = "Administrator";
const CB_PASSWORD = "password";

const rootAgent = new LlmAgent({
    model: "gemini-2.5-pro",
    name: "couchbase_agent",
    instruction: "协助用户探索和查询 Couchbase 数据库。",
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: ["couchbase-mcp-server"],
                env: {
                    CB_CONNECTION_STRING: CB_CONNECTION_STRING,
                    CB_USERNAME: CB_USERNAME,
                    CB_PASSWORD: CB_PASSWORD,
                    CB_MCP_READ_ONLY_MODE: "true", // 防止写入操作
                },
            },
        })
    ],
});

export { rootAgent };

可用工具¶

集群设置和健康检查工具¶

工具	描述
`get_server_configuration_status`	获取 MCP 服务器的状态
`test_cluster_connection`	通过连接集群来检查集群凭据
`get_cluster_health_and_services`	获取集群健康状态并列出所有运行中的服务

数据模型和 Schema 发现工具¶

工具	描述
`get_buckets_in_cluster`	获取集群中所有 Bucket 的列表
`get_scopes_in_bucket`	获取指定 Bucket 中所有 Scope 的列表
`get_collections_in_scope`	获取指定 Scope 和 Bucket 中所有 Collection 的列表
`get_scopes_and_collections_in_bucket`	获取指定 Bucket 中所有 Scope 和 Collection 的列表
`get_schema_for_collection`	获取 Collection 的结构

文档 KV 操作工具¶

工具	描述
`get_document_by_id`	从指定的 Scope 和 Collection 中根据 ID 获取文档
`upsert_document_by_id`	根据 ID 在指定的 Scope 和 Collection 中更新或插入 (Upsert) 文档。当 `CB_MCP_READ_ONLY_MODE=true` 时禁用。
`insert_document_by_id`	根据 ID 插入新文档（如果文档已存在则失败）。当 `CB_MCP_READ_ONLY_MODE=true` 时禁用。
`replace_document_by_id`	根据 ID 替换现有文档（如果文档不存在则失败）。当 `CB_MCP_READ_ONLY_MODE=true` 时禁用。
`delete_document_by_id`	从指定的 Scope 和 Collection 中根据 ID 删除文档。当 `CB_MCP_READ_ONLY_MODE=true` 时禁用。

查询和索引工具¶

工具	描述
`run_sql_plus_plus_query`	在指定的 Scope 上运行 SQL++ 查询
`list_indexes`	列出集群中所有的索引及其定义，可按 Bucket、Scope、Collection 和索引名称进行可选过滤
`get_index_advisor_recommendations`	从 Couchbase Index Advisor 获取针对给定 SQL++ 查询的索引建议，以优化查询性能

查询性能分析工具¶

工具	描述
`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`	获取非选择性查询（索引扫描返回的文档数远多于最终结果）

配置¶

环境变量¶

变量	描述	默认值
`CB_CONNECTION_STRING`	Couchbase 集群连接字符串	必填
`CB_USERNAME`	基础身份验证用户名	必填（或用于 mTLS 的客户端证书）
`CB_PASSWORD`	基础身份验证密码	必填（或用于 mTLS 的客户端证书）
`CB_CLIENT_CERT_PATH`	用于 mTLS 验证的客户端证书文件路径	无
`CB_CLIENT_KEY_PATH`	用于 mTLS 验证的客户端密钥文件路径	无
`CB_CA_CERT_PATH`	用于 TLS 的服务器根证书路径（Capella 不需要）	无
`CB_MCP_READ_ONLY_MODE`	防止所有数据修改（KV 和查询）	`true`
`CB_MCP_DISABLED_TOOLS`	以逗号分隔的禁用工具列表	无

只读模式¶

CB_MCP_READ_ONLY_MODE 设置（默认启用）将服务器限制为只读操作。启用后，KV 写入工具（upsert_document_by_id、insert_document_by_id、replace_document_by_id、delete_document_by_id）不会加载，并且会阻止修改数据的 SQL++ 查询。这使得你可以安全地进行数据探索，而没有意外修改的风险。

禁用工具¶

你可以使用 CB_MCP_DISABLED_TOOLS 禁用特定工具：

env={
    "CB_CONNECTION_STRING": "couchbase://localhost",
    "CB_USERNAME": "Administrator",
    "CB_PASSWORD": "password",
    "CB_MCP_DISABLED_TOOLS": "get_index_advisor_recommendations,get_queries_not_selective",
}