Couchbase

Servidor MCP do Couchbase

O Servidor MCP do Couchbase é um servidor auto-hospedado de Model Context Protocol (MCP) que conecta agentes de IA e assistentes com tecnologia de LLM — Claude, Cursor, Windsurf, VS Code Copilot e outros clientes MCP — a dados em clusters Couchbase, seja hospedados no Capella ou autogerenciados. MCP é um padrão aberto que permite que assistentes de IA chamem ferramentas e consultem fontes de dados externas; este servidor implementa esse padrão para o Couchbase, permitindo que um agente de IA inspecione seu cluster, execute consultas SQL++, leia e grave documentos e analise o desempenho de consultas usando linguagem natural em vez de código escrito manualmente.

Ele fornece ferramentas em categorias que incluem Saúde do Cluster, Esquema de Dados, Key-Value, Consulta e Desempenho — com controles de segurança por meio do modo somente leitura (ativado por padrão) e desativação granular de ferramentas, permitindo que um agente de IA explore e consulte seus dados sem risco de gravações não intencionais. Ele suporta transportes STDIO e HTTP Streamable.

O servidor MCP do Couchbase é distribuído como um pacote do Python Package Index (PyPI) e via Docker. O suporte empresarial para o Servidor MCP do Couchbase está disponível mediante licenciamento do Couchbase AI Data Plane, que também inclui o uso e o suporte empresarial do Couchbase Agent Memory e do Couchbase Agent Catalog.

Para documentação completa, visite mcp-server.couchbase.com.

Para documentação completa, visite docs.couchbase.com/mcp-server.

Sumário

• Por que o Servidor MCP do Couchbase
• Exemplos de Prompts
• Recursos/Ferramentas
• Pré-requisitos
• Configuração
• Servidor de Insights Operacionais
• Modo de Transporte HTTP Streamable
• Modo de Transporte SSE
• Autorização OAuth 2.1
• Imagem Docker
• Coleta de Dados de Uso
• Dicas de Solução de Problemas
• Testes de Integração
• FAQ
• Contribuição
• Política de Suporte

Por que o Servidor MCP do Couchbase

• Seguro por padrão — operações de gravação (upserts/inserções/exclusões de documentos e consultas SQL++ que modificam dados) são bloqueadas a menos que você defina explicitamente CB_MCP_READ_ONLY_MODE=false, e ferramentas individuais podem ser desativadas ou protegidas por confirmação do usuário.
• Funciona com clusters Capella e autogerenciados — a mesma configuração conecta-se ao Couchbase Capella (totalmente gerenciado) ou a um cluster Couchbase Server auto-hospedado.
• Ciente de RBAC — a desativação de ferramentas é uma camada de conveniência para orientar o comportamento do LLM; o controle de acesso baseado em funções do usuário Couchbase subjacente permanece como o limite de segurança autoritativo.
• Transportes de produção — execute via STDIO para clientes desktop locais, ou HTTP Streamable com OAuth 2.1 opcional (JWT/JWKS, agnóstico de provedor — Auth0, Okta, Keycloak, Entra, Cognito, etc.) para implantações compartilhadas/remotas.
• Qualquer cliente MCP — testado com Claude Desktop, Cursor, Windsurf, VS Code e JetBrains AI Assistant/Junie; funciona com qualquer cliente que implemente a especificação MCP.

Exemplos de Prompts

Depois que o servidor estiver conectado, você pode conversar com seu cluster Couchbase em linguagem natural por meio do seu assistente de IA. Por exemplo:

• "Quais buckets, scopes e coleções existem neste cluster e qual é o esquema da coleção orders?"
• "Execute uma consulta SQL++ para encontrar os 10 documentos mais recentes na coleção users where status = 'active'."
• "Quais são as 5 consultas mais lentas neste cluster na última hora, e alguma delas está sem um índice de cobertura?"
• "Verifique se este cluster está saudável e informe quais serviços estão em execução."
• "Insira um novo documento na coleção products com estes campos: ..." (requer CB_MCP_READ_ONLY_MODE=false)

Recursos/Ferramentas

Esta distribuição inclui dois servidores: o servidor operacional (padrão — as tabelas imediatamente abaixo) comunica-se com um cluster Couchbase regular via SDK couchbase, e o servidor Operational Insights (sua própria tabela mais abaixo) comunica-se com clusters Operational Insights via SDK couchbase-operational-insights.

Ferramentas de configuração e saúde do cluster

Ferramentas de descoberta de modelo de dados e esquema

Ferramentas de operações KV de documentos

Ferramentas de consulta e indexação

Ferramentas de pesquisa de texto completo (FTS)

Requer Couchbase Server 7.6+ e o serviço Search. A pesquisa vetorial não é suportada por estas ferramentas (consulte as ferramentas separadas de pesquisa vetorial).

Ferramentas de análise de desempenho de consultas

Ferramentas de Operational Insights

Registradas pelo servidor separado operational-insights (consulte Operational Insights Server abaixo), não pelo servidor padrão operational.

As ferramentas da API de Solicitação Assíncrona do Servidor formam um fluxo iniciar → consultar → descartar-ou-cancelar para consultas de longa duração: run_query_async retorna um query_handle, get_async_query_results é consultado até reportar prontidão (e retornar as linhas), então ou discard_async_query_results libera os resultados ou, para uma consulta ainda em execução, cancel_async_query a interrompe.

Nota: get_collections_in_scope, get_schema_for_collection, create_index e list_indexes existem, com comportamento diferente, em ambos os servidores. (get_server_configuration_status também aparece em ambos, mas é deliberadamente uma ferramenta compartilhada — mesma implementação, mesma forma de resultado — portanto não precisa de desambiguação.) Cada servidor é um processo separado, então isso só é uma preocupação se um único cliente MCP registrar tanto operational quanto operational-insights simultaneamente — nesse caso, desambigue na camada de configuração do cliente (por exemplo, dando aos dois registros do servidor nomes distintos na configuração do próprio cliente).

Pré-requisitos

• Python 3.10 ou superior.
• Um cluster Couchbase em execução. A maneira mais fácil de começar é usar o Capella no nível gratuito, que é a versão totalmente gerenciada do servidor Couchbase. Você pode seguir as instruções para importar um dos conjuntos de dados de exemplo ou importar os seus próprios.
• uv instalado para executar o servidor.
• Um cliente MCP como o Claude Desktop instalado para conectar o servidor ao Claude. As instruções são fornecidas para Claude Desktop e Cursor. Outros clientes MCP também podem ser usados.

Configuração

O servidor MCP pode ser executado a partir do pacote PyPI pré-compilado ou do código-fonte usando uv.

Executando a partir do PyPI

Publicamos um pacote PyPI pré-compilado para o servidor MCP.

Configuração do Servidor usando Pacote Pré-compilado para Clientes MCP

Autenticação Básica

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

ou

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

Nota: Se você tiver outros servidores MCP em uso no cliente, pode adicioná-lo ao objeto mcpServers existente.

Executando a partir do Código-Fonte

O servidor MCP pode ser executado a partir do código-fonte usando este repositório.

Clone o repositório para sua máquina local

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

Configuração do Servidor usando Código-Fonte para Clientes MCP

Esta é a configuração comum para clientes MCP como 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"
      }
    }
  }
}

Nota: path/to/cloned/repo/mcp-server-couchbase/ deve ser o caminho para o repositório clonado em sua máquina local. Não se esqueça da barra final!

Nota: Se você tiver outros servidores MCP em uso no cliente, pode adicioná-lo ao objeto mcpServers existente.

Configuração Adicional para o Servidor MCP

O servidor pode ser configurado usando variáveis de ambiente ou argumentos de linha de comando:

Configuração do Modo Somente Leitura

CB_MCP_READ_ONLY_MODE é o único interruptor que controla operações de escrita:

• Quando true (padrão): Todas as operações de escrita (KV, Query, gerenciamento de escopo/coleção e gerenciamento de índices) estão desabilitadas. Todas as ferramentas de escrita (KV: upsert, insert, replace, delete, mutação de sub-documento; gerenciamento de escopo/coleção: create_scope, create_collection, delete_scope, delete_collection; gerenciamento de índices: create_index, build_index, drop_index) não são carregadas e não estarão disponíveis para o LLM, e consultas SQL++ que modificam dados ou estrutura são bloqueadas.
• Quando false: Todas as ferramentas de escrita são carregadas e consultas SQL++ de modificação de dados/estrutura são permitidas.

Este é o padrão seguro recomendado para evitar modificações acidentais de dados por LLMs.

Nota: Para autenticação, você precisa do Nome de Usuário e Senha ou dos caminhos do Certificado e Chave do Cliente. Opcionalmente, você pode especificar o caminho do certificado raiz da CA que será usado para validar os certificados do servidor. Se tanto o caminho do Certificado e Chave do Cliente quanto o nome de usuário e senha forem especificados, os certificados do cliente serão usados para autenticação.

Desabilitando Ferramentas

Você pode desabilitar ferramentas específicas para impedir que sejam carregadas e expostas ao cliente MCP. Ferramentas desabilitadas não aparecerão na descoberta de ferramentas e não poderão ser invocadas pelo LLM.

Formatos Suportados

Lista separada por vírgulas:

# 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

Caminho de arquivo (um nome de ferramenta por linha):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Formato de arquivo (ex.: disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Linhas que começam com # são tratadas como comentários e ignoradas.

Exemplos de Configuração do Cliente MCP

Usando lista separada por vírgulas:

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

Usando caminho de arquivo (recomendado para muitas ferramentas):

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

Nota de Segurança Importante

Aviso: Desabilitar ferramentas por si só não garante que determinadas operações não possam ser executadas. As permissões RBAC (Controle de Acesso Baseado em Funções) do usuário do banco de dados subjacente são o controle de segurança autoritativo.

Por exemplo, mesmo se você desabilitar upsert_document_by_id e delete_document_by_id, modificações de dados ainda podem ocorrer por meio da ferramenta run_sql_plus_plus_query usando instruções DML do SQL++ (INSERT, UPDATE, DELETE, MERGE), a menos que:

• O CB_MCP_READ_ONLY_MODE esteja definido como true (padrão), OU
• O usuário do banco de dados não tenha as permissões RBAC necessárias para modificação de dados

Melhor Prática: Sempre configure permissões RBAC apropriadas nas credenciais do seu usuário Couchbase como medida de segurança primária. Use a desabilitação de ferramentas como uma camada adicional para orientar o comportamento do LLM e reduzir a superfície de ataque, não como o único controle de segurança.

Elicitação/Confirmação para Chamadas de Ferramentas

Você pode exigir confirmação explícita do usuário para ferramentas específicas antes da execução (quando o cliente MCP suporta elicitação).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools suporta estes formatos:

• Lista separada por vírgulas
• Caminho de arquivo (um nome de ferramenta por linha, comentários # suportados)

Exemplo:

# 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

Quando uma ferramenta listada é invocada:

• Se o cliente suporta elicitação, o usuário é solicitado a confirmar.
• Se o cliente não suporta elicitação, a ferramenta executa sem confirmação para compatibilidade retroativa.

Você também pode verificar a versão do servidor usando:

uvx couchbase-mcp-server --version

Registro de Logs

O servidor MCP registra logs em stderr por padrão. O registro de logs é configurado com as variáveis CB_MCP_LOG_* listadas em Configuração Adicional:

• CB_MCP_LOG_LEVEL — quanto é registrado: info (o padrão) registra eventos de ciclo de vida e invocações de ferramentas, debug adiciona detalhes internos detalhados, e off desabilita todo o registro de logs.
• CB_MCP_LOG_SINKS — para onde os logs vão: stderr (o padrão), arquivos rotativos por nível (file), ou ambos. Com file, um arquivo é gravado por nível (por exemplo, mcp_server.info.log e mcp_server.error.log) no caminho definido por CB_MCP_LOG_FILE.
• Tamanho de rotação — CB_MCP_LOG_ROTATION_MAX_SIZE_MB é o tamanho global (em MB) no qual cada arquivo por nível é rotacionado. Substitua níveis individuais com CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), também em MB, que herdam o global quando não definidos. Um tamanho de 0 (global ou por nível) é inválido e volta ao padrão (1 MB) com um aviso na inicialização. CB_MCP_LOG_MAX_BYTES (bytes) está obsoleto, mas ainda é respeitado para compatibilidade retroativa; é ignorado quando CB_MCP_LOG_ROTATION_MAX_SIZE_MB também está definido e imprime um aviso de depreciação na inicialização.
• Retenção — CB_MCP_LOG_RETENTION_BACKUP_COUNT define quantos backups rotacionados são mantidos por nível (excluindo o arquivo ativo); o padrão de 1 preserva o comportamento anterior. Substitua níveis individuais com CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), que herdam o valor global quando não definidos. Defina uma contagem para 0 para manter apenas o arquivo ativo para esse nível — ele ainda é limitado pelo tamanho de rotação (redefinido na rotação em vez de fazer backup).
• Instantâneo da configuração do servidor — quando o coletor file está ativo, um registro único (SO, Python, versões de dependências, transporte, configuração de log resolvida e configuração do servidor editada) é gravado como JSON em um arquivo mcp_server_config.log.json dedicado (derivado da base CB_MCP_LOG_FILE). Ele é sobrescrito a cada inicialização, então o suporte sempre tem a configuração atual e ela nunca sai de um log rotativo.

# 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

Para mais detalhes, consulte a documentação.

Configuração Específica do Cliente

Servidor de Insights Operacionais

Junto com o servidor operational padrão (aquele que cada seção acima descreve), esta distribuição inclui um segundo servidor para clusters de Insights Operacionais, usando o SDK separado couchbase-operational-insights. É um produto diferente de um cluster Couchbase regular e executa como um processo independente em sua própria porta.

Execute-o passando operational-insights como o subcomando da CLI (ou anexando-o como o comando do contêiner):

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 é uma URL HTTP(S), não uma string de conexão couchbase:// — ex.: http://localhost:8095 para um servidor local de Insights Operacionais, ou https://<host>:18095 para Capella. Este é o erro de configuração mais comum ao apontar este servidor para um cluster.

Todas as outras flags (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) são idênticas às do servidor operacional — veja Configuração Adicional para o Servidor MCP — exceto os padrões para porta (8001, não 8000) e arquivo de log (mcp_server_operational_insights.log, não mcp_server.log), já que dois servidores não podem compartilhar nenhum dos dois. OAuth usa os mesmos rótulos de escopo (couchbase-mcp:read / couchbase-mcp:write) que o servidor operacional, então uma configuração de IdP existente funciona para ambos sem alterações.

Exemplo de configuração de cliente 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"
      }
    }
  }
}

Veja Ferramentas do Operational Insights acima para a lista de ferramentas, e a nota sobre os três nomes de ferramentas compartilhados com o servidor operacional.

Ambos os servidores compartilham uma única listagem no Registro MCP, io.github.couchbase/mcp-server-couchbase, publicada a partir de server.json. A listagem tem uma entrada de pacote separada para cada servidor (PyPI e Docker). Cada entrada passa seu subcomando (operational ou operational-insights) e declara apenas os argumentos e variáveis de ambiente desse servidor.

Modo de Transporte HTTP Streamable

O Servidor MCP pode ser executado no modo de transporte HTTP Streamable, que permite que vários clientes se conectem à mesma instância do servidor via HTTP. Verifique se o seu cliente MCP suporta transporte HTTP streamable antes de tentar conectar ao servidor MCP neste modo.

Nota: A autorização OAuth 2.1 é suportada neste transporte. Veja Autorização OAuth 2.1. Sem OAuth configurado, o endpoint HTTP não é autenticado.

Uso

Por padrão, o servidor MCP será executado na porta 8000, mas isso pode ser configurado usando a variável de ambiente --port ou CB_MCP_PORT.

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

O servidor estará disponível em http://localhost:8000/mcp. Isso pode ser usado em clientes MCP que suportam o modo de transporte HTTP streamable, como o Cursor.

Configuração do Cliente MCP

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

Modo de Transporte SSE

Há uma opção para executar o servidor MCP no modo de transporte Server-Sent Events (SSE).

Nota: O modo SSE foi descontinuado pelo MCP. Temos suporte para HTTP Streamable.

SSE: Uso

Por padrão, o servidor MCP será executado na porta 8000, mas isso pode ser configurado usando a variável de ambiente --port ou CB_MCP_PORT.

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

O servidor estará disponível em http://localhost:8000/sse. Isso pode ser usado em clientes MCP que suportam o modo de transporte SSE, como o Cursor.

SSE: Configuração do Cliente MCP

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

Autorização OAuth 2.1

Ao executar com --transport=http, o servidor MCP pode atuar como um servidor de recursos OAuth 2.1: ele valida JWTs de portador recebidos contra o JWKS do seu provedor de identidade. É agnóstico de provedor (qualquer provedor OAuth 2.1 / OIDC que publique um JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) e não emite tokens nem gerencia usuários. As configurações de OAuth são ignoradas em stdio.

O OAuth é configurado com as variáveis CB_MCP_OAUTH_* listadas em Configuração Adicional:

• O OAuth ativa somente quando todas as três CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER e CB_MCP_OAUTH_JWT_AUDIENCE estão definidas; definir apenas algumas delas falha na inicialização.
• Definir CB_MCP_OAUTH_MCP_BASE_URL adicionalmente publica Metadados de Recursos Protegidos RFC 9728 para que clientes com reconhecimento de PRM possam descobrir o servidor de autorização.
• O acesso é controlado por dois escopos lidos da declaração scope/scp do token: couchbase-mcp:read (ferramentas de leitura, incluindo SQL++) e couchbase-mcp:write (ferramentas de escrita: mutações KV, gerenciamento de escopo/coleção e gerenciamento de índices). Acesso total requer ambos. Se o seu IdP não puder emitir esses rótulos canônicos, substitua-os com 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>'

Para detalhes completos, veja a documentação.

Imagem Docker

O servidor MCP também pode ser construído e executado como um contêiner Docker. Imagens pré-construídas podem ser encontradas no DockerHub ou puxadas via docker pull docker.io/couchbase/mcp-server:latest.

Alternativamente, fazemos parte do Catálogo MCP do Docker.

Construindo a Imagem

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

Executando

O servidor MCP pode ser executado com as variáveis de ambiente sendo usadas para configurar as configurações do Couchbase. As variáveis de ambiente são as mesmas descritas na seção de Configuração Adicional.

Contêiner Docker Independente

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

As variáveis de ambiente CB_MCP_PORT e CB_MCP_HOST são aplicáveis apenas no caso de modos de transporte HTTP como http e sse.

Docker: Configuração do Cliente MCP

A imagem Docker pode ser usada no modo de transporte stdio com a seguinte configuração.

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

Notas

• O valor de couchbase_connection_string depende se o servidor Couchbase está rodando na mesma máquina host, em outro contêiner Docker, ou em um host remoto. Se o seu servidor Couchbase estiver rodando na sua máquina host, sua string de conexão provavelmente será da forma couchbase://host.docker.internal. Para detalhes, consulte a documentação do docker.
• Você pode especificar a rede do contêiner usando a opção --network=<your_network>. A rede que você escolher depende do seu ambiente; o padrão é bridge. Para detalhes, consulte drivers de rede no docker.

Riscos Associados a LLMs

• O uso de modelos de linguagem de grande porte e tecnologia similar envolve riscos, incluindo o potencial de saídas imprecisas ou prejudiciais.
• A Couchbase não revisa nem avalia a qualidade ou precisão de tais saídas, e tais saídas podem não refletir as opiniões da Couchbase.
• Você é o único responsável por decidir se usa modelos de linguagem de grande porte e tecnologia relacionada, e por cumprir quaisquer termos de licença, termos de uso e políticas da sua organização que regem o seu uso dos mesmos.

Coleta de Dados de Uso

Este produto coleta automaticamente dados de uso e desempenho (como nome e versão do produto) e informações do navegador (como endereço IP) (coletivamente, "Dados de Uso"). A Couchbase usa os Dados de Uso, juntamente com outros dados que você pode fornecer à Couchbase (como seu nome de usuário ou endereço de e-mail), para desenvolver e melhorar nossos produtos, bem como informar nossos programas de vendas e marketing. Não acessamos nem coletamos dados que você armazena nos produtos da Couchbase. Usamos os Dados de Uso para entender padrões de uso agregados e tornar nossos produtos mais úteis para você. Para mais informações sobre como a Couchbase coleta, protege e processa informações, consulte a Política de Privacidade da Couchbase disponível em https://www.couchbase.com/privacy-policy.

Dicas de Solução de Problemas

• Certifique-se de que o caminho para o repositório do seu servidor MCP esteja correto na configuração se estiver executando a partir do código-fonte.
• Verifique se sua string de conexão do Couchbase, nome de usuário do banco de dados, senha ou o caminho para os certificados estão corretos.
• Se estiver usando o Couchbase Capella, certifique-se de que o cluster esteja acessível a partir da máquina onde o servidor MCP está rodando.
• Verifique se o usuário do banco de dados tem permissões adequadas para acessar pelo menos um bucket.
• Confirme se o gerenciador de pacotes uv está instalado e acessível corretamente. Você pode precisar fornecer o caminho absoluto para uv/uvx no campo command na configuração.
• Verifique os logs para quaisquer erros ou avisos que possam indicar problemas com o servidor MCP. A localização dos logs depende do seu cliente MCP.
• Se você estiver observando problemas ao executar seu servidor MCP a partir do código-fonte após atualizar seu repositório local do servidor MCP, tente executar uv sync para atualizar as dependências.

Testes de Integração

Fornecemos testes de integração MCP de alto nível para verificar se o servidor expõe as ferramentas esperadas e se elas podem ser invocadas contra um cluster Couchbase de demonstração.

1. Exporte as credenciais do cluster de demonstração:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Opcional: CB_MCP_TEST_BUCKET (um bucket para sondar durante os testes)
   • Opcional, para os testes do próprio servidor Operational Insights: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Esses testes são pulados automaticamente (não falham) quando não definidos.
2. Execute os testes:

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

FAQ

O que é o Servidor MCP do Couchbase? É uma implementação auto-hospedada do Model Context Protocol que permite que assistentes e agentes de IA (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, e qualquer outro cliente MCP) consultem e, opcionalmente, modifiquem dados em um cluster Couchbase usando linguagem natural.

Como conecto o Claude Desktop ao Couchbase? Instale o servidor com uvx couchbase-mcp-server (ou execute-o a partir do código-fonte ou Docker), então adicione sua configuração ao claude_desktop_config.json do Claude Desktop conforme mostrado em Configuração. Reinicie o Claude Desktop e ele detectará as novas ferramentas.

Posso usar isso com o Couchbase Capella? Sim. A mesma configuração de CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (ou certificado mTLS) funciona tanto para clusters Couchbase Capella quanto para clusters Couchbase Server autogerenciados.

É seguro deixar um agente de IA escrever no meu banco de dados? Por padrão, CB_MCP_READ_ONLY_MODE é verdadeiro, então todas as operações de escrita — upserts/inserções/substituições/exclusões de documentos e declarações SQL++ de modificação de dados — estão desabilitadas e as ferramentas de escrita nem são carregadas. Você também pode desabilitar ferramentas individuais (veja Desabilitando Ferramentas) ou exigir confirmação explícita do usuário antes que ferramentas específicas sejam executadas (veja Elicitação/Confirmação). Os controles em nível de ferramenta orientam o comportamento do LLM; as permissões RBAC do seu usuário Couchbase permanecem o verdadeiro limite de segurança.

Posso executar consultas em linguagem natural contra meus dados sem escrever SQL++ eu mesmo? Sim — pergunte ao seu assistente de IA uma pergunta em português simples (por exemplo, "mostre-me os 10 pedidos mais recentes acima de $100") e ele pode traduzir isso em uma consulta SQL++ usando a ferramenta run_sql_plus_plus_query. Você também pode pedir ao assistente para explain_sql_plus_plus_query uma consulta ou pedir recomendações ao consultor de índices. Qual é a diferença entre os transportes STDIO, Streamable HTTP e SSE? STDIO é para um único cliente MCP local (ex.: Claude Desktop) que inicia o servidor como um subprocesso. Streamable HTTP permite que vários clientes compartilhem uma única instância do servidor em execução via HTTP e suporta OAuth 2.1. SSE é o transporte HTTP mais antigo, agora descontinuado pela especificação MCP em favor do Streamable HTTP — veja Modo de Transporte Streamable HTTP.

Isso é oficialmente suportado pela Couchbase? Este projeto é mantido pela comunidade Couchbase — veja Política de Suporte. Suporte empresarial está disponível separadamente por meio do Couchbase AI Data Plane.

Contribuindo

Aceitamos contribuições da comunidade! Seja para corrigir bugs, adicionar recursos ou melhorar a documentação, sua ajuda é apreciada.

Se precisar de ajuda, encontrou um bug ou deseja contribuir com melhorias, o melhor lugar para fazer isso é aqui mesmo — abrindo uma issue no GitHub.

Para Desenvolvedores

Se você tem interesse em contribuir com código ou configurar um ambiente de desenvolvimento:

📖 Veja CONTRIBUTING.md para instruções abrangentes de configuração para desenvolvedores, incluindo:

• Configuração do ambiente de desenvolvimento com uv
• Linting e formatação de código com Ruff
• Instalação de hooks de pré-commit
• Visão geral da estrutura do projeto
• Fluxo de trabalho e práticas de desenvolvimento

Início Rápido para Contribuidores

# 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

📢 Política de Suporte

Agradecemos sinceramente seu interesse neste projeto! Este projeto é mantido pela comunidade Couchbase, o que significa que não é oficialmente suportado pela nossa equipe de suporte. No entanto, nossos engenheiros estão monitorando e mantendo ativamente este repositório e tentarão resolver problemas com base no melhor esforço.

Nosso portal de suporte não consegue ajudar com solicitações relacionadas a este projeto, então pedimos gentilmente que todas as consultas permaneçam no GitHub.

Sua colaboração nos ajuda a avançar juntos — obrigado!