Couchbase

Servidor MCP de Couchbase

Couchbase MCP Server es un servidor MCP auto-gestionado que permite a los agentes de IA conectarse e interactuar con datos en clústeres de Couchbase, ya sea alojados en Capella o auto-gestionados. Proporciona herramientas en categorías que incluyen Salud del Clúster, Esquema de Datos, Clave-Valor, Consultas y Rendimiento, con controles de seguridad mediante modo de solo lectura y desactivación detallada de herramientas. Soporta transportes STDIO y HTTP Streamable.

El servidor MCP de Couchbase se distribuye como un paquete de Python Package Index (PyPI) y a través de Docker. El soporte empresarial para Couchbase MCP Server está disponible mediante la licencia de Couchbase AI Data Plane, que también autoriza el uso y soporte empresarial de Couchbase Agent Memory y Couchbase Agent Catalog.

Para la documentación completa, visite mcp-server.couchbase.com.

Características/Herramientas

Herramientas de configuración y salud del clúster

Herramientas de descubrimiento de modelo de datos y esquema

Herramientas de operaciones KV de documentos

Herramientas de consulta e indexación

Herramientas de análisis de rendimiento de consultas

Requisitos previos

• Python 3.10 o superior.
• Un clúster de Couchbase en ejecución. La forma más fácil de empezar es usar el nivel gratuito de Capella, que es una versión completamente gestionada del servidor Couchbase. Puede seguir las instrucciones para importar uno de los conjuntos de datos de muestra o importar el suyo propio.
• uv instalado para ejecutar el servidor.
• Un cliente MCP como Claude Desktop instalado para conectar el servidor a Claude. Las instrucciones se proporcionan para Claude Desktop y Cursor. También se pueden usar otros clientes MCP.

Configuración

El servidor MCP se puede ejecutar desde el paquete PyPI preconstruido o desde el código fuente usando uv.

Ejecución desde PyPI

Publicamos un paquete PyPI preconstruido para el servidor MCP.

Configuración del servidor usando paquete preconstruido para clientes MCP

Autenticación básica

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

o

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: Si tiene otros servidores MCP en uso en el cliente, puede agregarlo al objeto mcpServers existente.

Ejecución desde el código fuente

El servidor MCP se puede ejecutar desde el código fuente utilizando este repositorio.

Clonar el repositorio en su máquina local

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

Configuración del servidor usando código fuente para clientes MCP

Esta es la configuración común para los 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/ debe ser la ruta al repositorio clonado en su máquina local. ¡No olvide la barra diagonal al final!

Nota: Si tiene otros servidores MCP en uso en el cliente, puede agregarlo al objeto mcpServers existente.

Configuración adicional para el servidor MCP

El servidor se puede configurar usando variables de entorno o argumentos de línea de comandos:

Configuración del Modo de Solo Lectura

CB_MCP_READ_ONLY_MODE es el único interruptor que controla las operaciones de escritura:

• Cuando true (predeterminado): Todas las operaciones de escritura (KV, Query, gestión de alcances/colecciones y gestión de índices) están deshabilitadas. Las herramientas de escritura KV (upsert, insert, replace, delete, sub-document mutate), las herramientas de escritura de gestión de alcances/colecciones (create_scope, create_collection, delete_scope, delete_collection) y las herramientas de escritura de índices (create_index, build_index, drop_index) no se cargan y no estarán disponibles para el LLM, y las consultas SQL++ que modifican datos o estructura están bloqueadas.
• Cuando false: Las herramientas de escritura de KV, gestión de alcances/colecciones e índices se cargan y se permiten consultas de modificación de datos/estructura SQL++.

Este es el valor predeterminado seguro recomendado para evitar modificaciones de datos inadvertidas por parte de los LLM.

Nota: Para la autenticación, necesita el Nombre de usuario y Contraseña o las rutas del Certificado de Cliente y clave. Opcionalmente, puede especificar la ruta del certificado raíz de CA que se usará para validar los certificados del servidor. Si se especifican tanto la ruta del Certificado de Cliente y clave como el nombre de usuario y contraseña, los certificados de cliente se usarán para la autenticación.

Deshabilitar herramientas

Puede deshabilitar herramientas específicas para evitar que se carguen y se expongan al cliente MCP. Las herramientas deshabilitadas no aparecerán en el descubrimiento de herramientas y no podrán ser invocadas por el LLM.

Formatos admitidos

Lista separada por comas:

# 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

Ruta de archivo (un nombre de herramienta por línea):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Formato de archivo (p. ej., disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Las líneas que comienzan con # se tratan como comentarios y se ignoran.

Ejemplos de configuración del cliente MCP

Usando lista separada por comas:

{
  "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 ruta de archivo (recomendado para muchas herramientas):

{
  "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 seguridad importante

Advertencia: Deshabilitar herramientas por sí solo no garantiza que ciertas operaciones no puedan realizarse. Los permisos RBAC (Control de Acceso Basado en Roles) del usuario de la base de datos subyacente son el control de seguridad autoritativo.

Por ejemplo, incluso si deshabilita upsert_document_by_id y delete_document_by_id, las modificaciones de datos aún pueden ocurrir a través de la herramienta run_sql_plus_plus_query usando sentencias DML de SQL++ (INSERT, UPDATE, DELETE, MERGE) a menos que:

• El CB_MCP_READ_ONLY_MODE esté configurado en true (predeterminado), O
• El usuario de la base de datos carezca de los permisos RBAC necesarios para la modificación de datos

Mejores prácticas: Configure siempre permisos RBAC apropiados en sus credenciales de usuario de Couchbase como medida de seguridad principal. Use la deshabilitación de herramientas como una capa adicional para guiar el comportamiento del LLM y reducir la superficie de ataque, no como el único control de seguridad.

Elicitación/Confirmación para llamadas a herramientas

Puede requerir confirmación explícita del usuario para herramientas específicas antes de la ejecución (cuando el cliente MCP admite elicitación).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools admite estos formatos:

• Lista separada por comas
• Ruta de archivo (un nombre de herramienta por línea, se admiten comentarios #)

Ejemplo:

# 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

Cuando se invoca una herramienta listada:

• Si el cliente admite elicitación, se solicita al usuario que confirme.
• Si el cliente no admite elicitación, la herramienta se ejecuta sin confirmación por compatibilidad hacia atrás.

También puede verificar la versión del servidor usando:

uvx couchbase-mcp-server --version

Registro

El servidor MCP registra en stderr de forma predeterminada. El registro se configura con las variables CB_MCP_LOG_* listadas en Configuración adicional:

• CB_MCP_LOG_LEVEL — cuánto se registra: info (el predeterminado) registra eventos del ciclo de vida e invocaciones de herramientas, debug agrega detalles internos verbosos, y off deshabilita todo el registro.
• CB_MCP_LOG_SINKS — a dónde van los registros: stderr (el predeterminado), archivos rotativos por nivel (file), o ambos. Con file, se escribe un archivo por nivel (por ejemplo mcp_server.info.log y mcp_server.error.log) en la ruta establecida por CB_MCP_LOG_FILE.
• Tamaño de rotación — CB_MCP_LOG_ROTATION_MAX_SIZE_MB es el tamaño global (en MB) en el que cada archivo por nivel rota. Anule niveles individuales con CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), también en MB, que heredan el global cuando no se configuran. Un tamaño de 0 (global o por nivel) no es válido y se revierte al predeterminado (1 MB) con una advertencia al inicio. CB_MCP_LOG_MAX_BYTES (bytes) está obsoleto pero aún se respeta por compatibilidad hacia atrás; se ignora cuando CB_MCP_LOG_ROTATION_MAX_SIZE_MB también está configurado, e imprime una advertencia de obsolescencia al inicio.
• Retención — CB_MCP_LOG_RETENTION_BACKUP_COUNT establece cuántos respaldos rotados se conservan por nivel (excluyendo el archivo activo); el predeterminado de 1 preserva el comportamiento anterior. Anule niveles individuales con CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), que heredan el valor global cuando no se configuran. Establezca un conteo en 0 para conservar solo el archivo activo para ese nivel — aún está limitado por el tamaño de rotación (se restablece en la rotación en lugar de respaldarse).
• Instantánea de configuración del servidor — cuando el sumidero file está activo, un registro único (SO, Python, versiones de dependencias, transporte, configuración de registro resuelta y configuración del servidor redactada) se escribe como JSON en un archivo mcp_server_config.log.json dedicado (derivado de la base CB_MCP_LOG_FILE). Se sobrescribe en cada inicio, por lo que el soporte siempre tiene la configuración actual y nunca se sale de un 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 más detalles, consulte la documentación.

Configuración específica del cliente

Modo de transporte Streamable HTTP

El servidor MCP se puede ejecutar en modo de transporte Streamable HTTP que permite que múltiples clientes se conecten a la misma instancia del servidor a través de HTTP. Verifica si tu cliente MCP admite el transporte streamable http antes de intentar conectarte al servidor MCP en este modo.

Nota: La autorización OAuth 2.1 es compatible con este transporte. Ver Autorización OAuth 2.1. Sin OAuth configurado, el punto final HTTP no está autenticado.

Uso

Por defecto, el servidor MCP se ejecutará en el puerto 8000 pero esto se puede configurar usando la variable de entorno --port o CB_MCP_PORT.

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

El servidor estará disponible en http://localhost:8000/mcp. Esto se puede usar en clientes MCP que admiten el modo de transporte streamable http, como Cursor.

Configuración de cliente MCP

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

Modo de transporte SSE

Existe la opción de ejecutar el servidor MCP en modo de transporte Eventos enviados por el servidor (SSE).

Nota: El modo SSE ha sido obsoleto por MCP. Contamos con soporte para Streamable HTTP.

Uso SSE

Por defecto, el servidor MCP se ejecutará en el puerto 8000 pero esto se puede configurar usando la variable de entorno --port o CB_MCP_PORT.

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

El servidor estará disponible en http://localhost:8000/sse. Esto se puede usar en clientes MCP que admiten el modo de transporte SSE, como Cursor.

Configuración de cliente MCP para SSE

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

Autorización OAuth 2.1

Cuando se ejecuta con --transport=http, el servidor MCP puede actuar como un servidor de recursos OAuth 2.1: valida los JWT de portador entrantes contra el JWKS de tu proveedor de identidad. Es independiente del proveedor (cualquier proveedor OAuth 2.1 / OIDC que publique un JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) y no emite tokens ni gestiona usuarios. La configuración de OAuth se ignora en stdio.

OAuth se configura con las variables CB_MCP_OAUTH_* listadas en Configuración adicional:

• OAuth se activa solo cuando las tres CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER y CB_MCP_OAUTH_JWT_AUDIENCE están configuradas; configurar solo algunas falla al inicio.
• Configurar CB_MCP_OAUTH_MCP_BASE_URL adicionalmente publica metadatos de recursos protegidos RFC 9728 para que los clientes compatibles con PRM puedan descubrir el servidor de autorización.
• El acceso está controlado por dos alcances leídos del reclamo scope/scp del token: couchbase-mcp:read (herramientas de lectura, incluyendo SQL++) y couchbase-mcp:write (herramientas de escritura: mutaciones de KV, gestión de ámbitos/colecciones y gestión de índices). El acceso completo requiere ambos. Si tu IdP no puede emitir esas etiquetas canónicas, anúlalas con 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 detalles completos, consulta la documentación.

Imagen Docker

El servidor MCP también se puede compilar y ejecutar como un contenedor Docker. Las imágenes precompiladas se pueden encontrar en DockerHub o se pueden extraer mediante docker pull docker.io/couchbase/mcp-server:latest.

Alternativamente, formamos parte del Catálogo MCP de Docker.

Compilación de la imagen

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

Ejecución

El servidor MCP se puede ejecutar con las variables de entorno utilizadas para configurar los ajustes de Couchbase. Las variables de entorno son las mismas que se describen en la sección de Configuración adicional.

Contenedor Docker independiente

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

Las variables de entorno CB_MCP_PORT y CB_MCP_HOST solo son aplicables en el caso de modos de transporte HTTP como http y sse.

Docker: Configuración de cliente MCP

La imagen Docker se puede usar en modo de transporte stdio con la siguiente configuración.

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

• El valor de couchbase_connection_string depende de si el servidor de Couchbase se está ejecutando en la misma máquina host, en otro contenedor Docker, o en un host remoto. Si tu servidor de Couchbase se está ejecutando en tu máquina host, tu cadena de conexión probablemente tendría la forma couchbase://host.docker.internal. Para detalles, consulta la documentación de Docker.
• Puedes especificar la red del contenedor usando la opción --network=<your_network>. La red que elijas depende de tu entorno; el valor predeterminado es bridge. Para detalles, consulta los controladores de red en Docker.

Riesgos asociados con los LLM

• El uso de modelos de lenguaje de gran tamaño y tecnología similar implica riesgos, incluida la posibilidad de salidas inexactas o dañinas.
• Couchbase no revisa ni evalúa la calidad o precisión de dichas salidas, y tales salidas pueden no reflejar las opiniones de Couchbase.
• Eres el único responsable de decidir si usar modelos de lenguaje de gran tamaño y tecnología relacionada, y de cumplir con cualquier término de licencia, términos de uso y las políticas de tu organización que regulan su uso.

Recolección de datos de uso

Este producto recopila automáticamente datos de uso y rendimiento (como el nombre y la versión del producto) e información del navegador (como la dirección IP) (colectivamente, "Datos de uso"). Couchbase utiliza los Datos de uso, junto con otros datos que puedas proporcionar a Couchbase (como tu nombre de usuario o dirección de correo electrónico), para desarrollar y mejorar nuestros productos, así como para informar nuestros programas de ventas y marketing. No accedemos ni recopilamos ningún dato que almacenes en los productos de Couchbase. Usamos los Datos de uso para comprender los patrones de uso agregados y hacer que nuestros productos sean más útiles para ti. Para obtener más información sobre cómo Couchbase recopila, protege y procesa la información, consulta la Política de Privacidad de Couchbase disponible en https://www.couchbase.com/privacy-policy.

Consejos para la resolución de problemas

• Asegúrate de que la ruta a tu repositorio del servidor MCP sea correcta en la configuración si se ejecuta desde el código fuente.
• Verifica que tu cadena de conexión de Couchbase, el nombre de usuario de la base de datos, la contraseña o la ruta a los certificados sean correctos.
• Si usas Couchbase Capella, asegúrate de que el clúster sea accesible desde la máquina donde se ejecuta el servidor MCP.
• Comprueba que el usuario de la base de datos tenga los permisos adecuados para acceder al menos a un bucket.
• Confirma que el gestor de paquetes uv esté correctamente instalado y accesible. Es posible que debas proporcionar la ruta absoluta a uv/uvx en el campo command de la configuración.
• Revisa los registros para detectar errores o advertencias que puedan indicar problemas con el servidor MCP. La ubicación de los registros depende de tu cliente MCP.
• Si observas problemas al ejecutar tu servidor MCP desde el código fuente después de actualizar tu repositorio local del servidor MCP, intenta ejecutar uv sync para actualizar las dependencias.

Pruebas de integración

Proporcionamos pruebas de integración MCP de alto nivel para verificar que el servidor expone las herramientas esperadas y que se pueden invocar contra un clúster de demostración de Couchbase.

1. Exporta las credenciales del clúster de demostración:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Opcional: CB_MCP_TEST_BUCKET (un bucket para sondear durante las pruebas)
2. Ejecuta las pruebas:

uv run pytest tests/ -v

👩‍💻 Contribuciones

¡Agradecemos las contribuciones de la comunidad! Ya sea que quieras corregir errores, agregar funciones o mejorar la documentación, tu ayuda es apreciada.

Si necesitas ayuda, has encontrado un error o quieres contribuir con mejoras, el mejor lugar para hacerlo es aquí mismo: abriendo un issue en GitHub.

Para desarrolladores

Si te interesa contribuir con código o configurar un entorno de desarrollo:

📖 Consulta CONTRIBUTING.md para obtener instrucciones completas de configuración para desarrolladores, que incluyen:

• Configuración del entorno de desarrollo con uv
• Linting y formato de código con Ruff
• Instalación de hooks de pre-commit
• Resumen de la estructura del proyecto
• Flujo de trabajo y prácticas de desarrollo

Inicio rápido para contribuyentes

# 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 soporte

¡Apreciamos sinceramente tu interés en este proyecto! Este proyecto es mantenido por la comunidad de Couchbase, lo que significa que no cuenta con soporte oficial de nuestro equipo de soporte. Sin embargo, nuestros ingenieros están monitoreando y manteniendo activamente este repositorio e intentarán resolver los problemas en la medida de lo posible.

Nuestro portal de soporte no puede ayudar con solicitudes relacionadas con este proyecto, por lo que solicitamos amablemente que todas las consultas se realicen dentro de GitHub.

¡Tu colaboración nos ayuda a avanzar juntos: gracias!