Couchbase MCP tool for ADK¶

Supported in ADKPythonTypeScript

The Couchbase MCP Server connects your ADK agent to Couchbase clusters. This integration gives your agent the ability to explore Couchbase data using natural language, including exploring data, running queries, and analyzing performance issues.

Use cases¶

Data Exploration: Discover buckets, scopes, collections, and document schemas, query data using natural language queries.
Database Administration: Monitor cluster health, check running services, and manage bucket, scope, and collection structures through conversational commands.
Query Performance Analysis: Get index recommendations, analyze query plans, and investigate slow or non-selective queries to optimize performance.

Prerequisites¶

A running Couchbase cluster. You can:
- Use Couchbase Capella (managed cloud service)
- Run Couchbase Server 7.x+ locally or self-hosted
Connection string and credentials (username/password or client certificate for mTLS) for the cluster
uv package manager installed (for the uvx command)

Use with agent¶

PythonTypeScript

Local MCP Server

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="Help users explore and query Couchbase databases",
    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",  # Prevents write operations
                    },
                ),
                timeout=60,
            ),
        )
    ],
)

Local MCP Server

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: "Help users explore and query Couchbase databases",
    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", // Prevents write operations
                },
            },
        })
    ],
});

export { rootAgent };

Available tools¶

Cluster setup and health tools¶

Tool	Description
`get_server_configuration_status`	Get the status of the MCP server
`test_cluster_connection`	Check the cluster credentials by connecting to the cluster
`get_cluster_health_and_services`	Get cluster health status and list of all running services

Data model and schema discovery tools¶

Tool	Description
`get_buckets_in_cluster`	Get a list of all the buckets in the cluster
`get_scopes_in_bucket`	Get a list of all the scopes in the specified bucket
`get_collections_in_scope`	Get a list of all the collections in a specified scope and bucket
`get_scopes_and_collections_in_bucket`	Get a list of all the scopes and collections in the specified bucket
`get_schema_for_collection`	Get the structure for a collection

Document KV operations tools¶

Tool	Description
`get_document_by_id`	Get a document by ID from a specified scope and collection
`upsert_document_by_id`	Upsert a document by ID to a specified scope and collection. Disabled when `CB_MCP_READ_ONLY_MODE=true`.
`insert_document_by_id`	Insert a new document by ID (fails if document exists). Disabled when `CB_MCP_READ_ONLY_MODE=true`.
`replace_document_by_id`	Replace an existing document by ID (fails if document doesn't exist). Disabled when `CB_MCP_READ_ONLY_MODE=true`.
`delete_document_by_id`	Delete a document by ID from a specified scope and collection. Disabled when `CB_MCP_READ_ONLY_MODE=true`.

Query and indexing tools¶

Tool	Description
`run_sql_plus_plus_query`	Run a SQL++ query on a specified scope
`list_indexes`	List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name
`get_index_advisor_recommendations`	Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance

Query performance analysis tools¶

Tool	Description
`get_longest_running_queries`	Get longest running queries by average service time
`get_most_frequent_queries`	Get most frequently executed queries
`get_queries_with_largest_response_sizes`	Get queries with the largest response sizes
`get_queries_with_large_result_count`	Get queries with the largest result counts
`get_queries_using_primary_index`	Get queries that use a primary index (potential performance concern)
`get_queries_not_using_covering_index`	Get queries that don't use a covering index
`get_queries_not_selective`	Get queries that are not selective (index scans return many more documents than final result)

Configuration¶

Environment variables¶

Variable	Description	Default
`CB_CONNECTION_STRING`	Connection string to the Couchbase cluster	Required
`CB_USERNAME`	Username for basic authentication	Required (or client certificate for mTLS)
`CB_PASSWORD`	Password for basic authentication	Required (or client certificate for mTLS)
`CB_CLIENT_CERT_PATH`	Path to the client certificate file for mTLS authentication	None
`CB_CLIENT_KEY_PATH`	Path to the client key file for mTLS authentication	None
`CB_CA_CERT_PATH`	Path to server root certificate for TLS (not required for Capella)	None
`CB_MCP_READ_ONLY_MODE`	Prevent all data modifications (KV and query)	`true`
`CB_MCP_DISABLED_TOOLS`	Comma-separated list of tools to disable	None

Read-only mode¶

The CB_MCP_READ_ONLY_MODE setting (enabled by default) restricts the server to read-only operations. When enabled, KV write tools (upsert_document_by_id, insert_document_by_id, replace_document_by_id, delete_document_by_id) are not loaded, and SQL++ queries that modify data are blocked. This makes it safe for data exploration without risk of accidental modifications.

Disabling tools¶

You can disable specific tools using 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",
}