Couchbase

Couchbase MCP Server

Couchbase MCP Server é um servidor MCP auto-hospedado que permite que agentes de IA se conectem e interajam com dados em clusters Couchbase, seja hospedados na Capella ou autogerenciados. Ele fornece ferramentas em categorias como Saúde do Cluster, Esquema de Dados, Key-Value, Consulta e Desempenho — com controles de segurança via modo somente leitura e desativação granular de ferramentas. Ele suporta transportes STDIO e HTTP Streamable.

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

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

Recursos/Ferramentas

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 análise de desempenho de consultas

Pré-requisitos

• Python 3.10 ou superior.
• Um cluster Couchbase em execução. A maneira mais fácil de começar é usar o nível gratuito do Capella, 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é-construído ou do código-fonte usando uv.

Executando a partir do PyPI

Publicamos um pacote PyPI pré-construído para o servidor MCP.

Configuração do Servidor usando Pacote Pré-construído 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, você 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 no final!

Nota: Se você tiver outros servidores MCP em uso no cliente, você 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. As ferramentas de escrita KV (upsert, insert, replace, delete, mutação de sub-documento), as ferramentas de escrita de gerenciamento de escopo/coleção (create_scope, create_collection, delete_scope, delete_collection) e as ferramentas de escrita 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: As ferramentas de escrita KV, gerenciamento de escopo/coleção e índices 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 inadvertidas de dados por LLMs.

Observação: Para autenticação, você precisa do Nome de Usuário e Senha ou do Certificado do Cliente e caminhos da chave. 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írgula:

# 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 começando com # são tratadas como comentários e ignoradas.

Exemplos de Configuração do Cliente MCP

Usando lista separada por vírgula:

{
  "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 certas operações não possam ser realizadas. 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 através da ferramenta run_sql_plus_plus_query usando instruções DML 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 a 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írgula
• 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 reversa.

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

uvx couchbase-mcp-server --version

Registro (Logging)

O servidor MCP registra em stderr por padrão. O registro é 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 verbosos, e off desabilita todo o registro.
• CB_MCP_LOG_SINKS — para onde os registros 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 rotaciona. Sobrescreva 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 reversa; é 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. Sobrescreva 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 aquele 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 sink file está ativo, um registro único (SO, Python, versões de dependências, transporte, configuração de registro resolvida e configuração do servidor com dados sensíveis mascarados) é 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 registro 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, veja a documentação.

Configuração Específica do Cliente

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. Consulte 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

Existe a opção de 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. Ele é 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 variáveis 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 os Metadados de Recurso Protegido RFC 9728 para que clientes cientes 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). O acesso total requer ambos. Se o seu IdP não puder emitir esses rótulos canônicos, substitua-os por 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, consulte 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 baixadas 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 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 terá a 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 grandes 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 essas saídas podem não refletir as opiniões da Couchbase.
• Você é o único responsável por decidir se usa modelos de linguagem grandes 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

• Garanta que o caminho para o repositório do servidor MCP esteja correto na configuração se estiver executando a partir do código-fonte.
• Verifique se a string de conexão do Couchbase, o nome de usuário do banco de dados, a senha ou o caminho para os certificados estão corretos.
• Se estiver usando o Couchbase Capella, garanta que o cluster esteja acessível a partir da máquina onde o servidor MCP está em execução.
• 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 corretamente e acessível. Talvez seja necessário fornecer o caminho absoluto para uv/uvx no campo command na configuração.
• Verifique os logs em busca de erros ou avisos que possam indicar problemas com o servidor MCP. A localização dos logs depende do seu cliente MCP.
• Se você estiver enfrentando 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)
2. Execute os testes:

uv run pytest tests/ -v

👩‍💻 Contribuindo

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

Se você 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:

📖 Consulte CONTRIBUTING.md para obter 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 pre-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 da melhor forma possível.

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

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