Couchbase

Servidor MCP Couchbase

O Servidor MCP Couchbase é um Servidor MCP auto-hospedado que permite que agentes de IA se conectem e interajam com dados em clusters Couchbase, sejam eles hospedados no Capella ou autogerenciados. Ele fornece ferramentas em categorias como Saúde do Cluster, Esquema de Dados, Chave-Valor, Consulta e Desempenho — com controles de segurança por meio do modo somente leitura e desabilitação granular de ferramentas. Ele suporta os 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 Servidor MCP Couchbase está disponível através do licenciamento do Couchbase AI Data Plane, que também concede direito de uso e suporte empresarial do Couchbase Agent Memory e Couchbase Agent Catalog.

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

Funcionalidades/Ferramentas

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

Ferramentas de descoberta de esquema e modelo de dados

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 é uma versão totalmente gerenciada do servidor Couchbase. Você pode seguir as instruções para importar um dos conjuntos de dados de amostra 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, poderá 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 no final!

Nota: Se você tiver outros servidores MCP em uso no cliente, poderá 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 as operações de escrita:

• Quando true (padrão): Todas as operações de escrita (KV e Consulta) estão desabilitadas. As ferramentas de escrita KV (upsert, insert, replace, delete) 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 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.

Nota: Para autenticação, você precisa do Nome de Usuário e Senha ou dos caminhos do Certificado de Cliente e chave. Opcionalmente, você pode especificar o caminho do certificado raiz da CA que será usado para validar os certificados do servidor. Se ambos, o Certificado de Cliente e caminho da chave e 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 podem 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 do 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 do 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 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 que você desabilite 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 de usuário do Couchbase como a medida de segurança primária. Use a desabilitação de ferramentas como uma camada adicional para guiar 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 é 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 logs vão: stderr (o padrão), arquivos rotativos por nível (file), ou ambos. Com file, um arquivo é escrito por nível (por exemplo mcp_server.info.log e mcp_server.error.log) no caminho definido por CB_MCP_LOG_FILE.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

Para mais detalhes, veja a documentação.

Configuração Específica do Cliente

Modo de Transporte HTTP Transmissível

O Servidor MCP pode ser executado no modo de transporte HTTP Transmissível, que permite que vários clientes se conectem à mesma instância do servidor via HTTP. Verifique se o seu cliente MCP suporta transporte http transmissível 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 transmissível, 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 Transmissível.

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 ao provedor (qualquer provedor OAuth 2.1 / OIDC que publique um JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) e não emite tokens ou gerencia usuários. As configurações OAuth são ignoradas em stdio.

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

• OAuth é ativado somente quando todos os três CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER e CB_MCP_OAUTH_JWT_AUDIENCE estão definidos; definir apenas alguns deles falha na inicialização.
• Definir CB_MCP_OAUTH_MCP_BASE_URL adicionalmente publica 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 mutação KV). Acesso total requer ambos.

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 obtidas 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

Execução

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

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

Observações

• O valor de couchbase_connection_string depende se o servidor Couchbase está rodando na mesma máquina host, em outro container 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á o formato couchbase://host.docker.internal. Para detalhes, consulte a documentação do docker.
• Você pode especificar a rede do container usando a opção --network=<your_network>. A rede escolhida 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 escala e tecnologia similar envolve riscos, incluindo o potencial para saídas imprecisas ou prejudiciais.
• O Couchbase não revisa ou avalia a qualidade ou precisão de tais saídas, e tais saídas podem não refletir as visões do Couchbase.
• Você é o único responsável por determinar se deve usar modelos de linguagem de grande escala e tecnologia relacionada, e por cumprir quaisquer termos de licença, termos de uso e políticas da sua organização que regem o uso dos mesmos.

Dicas de Solução de Problemas

• Certifique-se de que o caminho para o repositório do seu servidor MCP está 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 está 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 que o gerenciador de pacotes uv está devidamente instalado e acessível. Pode ser 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 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)
2. Execute os testes:

uv run pytest tests/ -v

👩‍💻 Contribuindo

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

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:

📖 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 genuinamente 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 o melhor esforço possível.

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

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