Couchbase

Servidor MCP de Couchbase

El Servidor MCP de Couchbase es un servidor MCP autogestionado que permite a los agentes de IA conectarse e interactuar con datos en clústeres de Couchbase, ya sea alojados en Capella o autogestionados. 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 Transmisible.

El servidor MCP de Couchbase se distribuye como un paquete del Índice de Paquetes de Python (PyPI) y a través de Docker. El soporte empresarial para el Servidor MCP de Couchbase está disponible mediante la licencia de Couchbase AI Data Plane, que también da derecho al 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 esquemas y modelo de datos

Herramientas de operaciones KV de documentos

Herramientas de consultas e indexación

Herramientas de análisis de rendimiento de consultas

Requisitos previos

• Python 3.10 o superior.
• Un clúster de Couchbase en funcionamiento. 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 podrían usar otros clientes MCP.

Configuración

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

Ejecución desde PyPI

Publicamos un paquete PyPI precompilado para el servidor MCP.

Configuración del Servidor usando el Paquete Precompilado 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 añadirlo al objeto mcpServers existente.

Ejecución desde el Código Fuente

El servidor MCP se puede ejecutar desde el código fuente usando 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 el 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 añadirlo 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 interruptor único que controla las operaciones de escritura:

• Cuando true (por defecto): Todas las operaciones de escritura (KV y Consultas) están desactivadas. Las herramientas de escritura KV (upsert, insert, replace, delete) no se cargan y no estarán disponibles para el LLM, y las consultas SQL++ que modifican datos o estructura se bloquean.
• Cuando false: Las herramientas de escritura KV se cargan y se permiten las consultas SQL++ de modificación de datos/estructura.

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

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

Desactivación de Herramientas

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

Formatos Soportados

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 (por ejemplo, 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 base de datos subyacente son el control de seguridad autoritativo.

Por ejemplo, incluso si deshabilitas 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:

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

Mejor práctica: Configura siempre los permisos RBAC apropiados en tus credenciales de usuario de Couchbase como medida de seguridad principal. Usa 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.

Obtención/Confirmación para Llamadas a Herramientas

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

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

• Lista separada por comas
• Ruta de archivo (un nombre de herramienta por línea, se soportan 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 soporta obtención, se solicita al usuario que confirme.
• Si el cliente no soporta obtención, la herramienta se ejecuta sin confirmación para compatibilidad con versiones anteriores.

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

uvx couchbase-mcp-server --version

Registro

El servidor MCP registra en stderr por defecto. 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 añade detalle interno detallado, 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.

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

Para más detalles, consulta la documentación.

Configuración Específica del Cliente

Modo de Transporte HTTP Transmisible

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

Nota: La autorización OAuth 2.1 está soportada en este transporte. Consulta Autorización OAuth 2.1. Sin OAuth configurado, el endpoint 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 soporten el modo de transporte http transmisible como Cursor.

Configuración del Cliente MCP

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

Modo de Transporte SSE

Existe una opción para ejecutar el servidor MCP en modo de transporte Eventos Enviados por el Servidor (SSE).

Nota: El modo SSE ha sido obsoleto por MCP. Tenemos soporte para HTTP Transmisible.

SSE: 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=sse

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

SSE: Configuración del Cliente MCP

{
  "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 agnóstico al 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 de ellas falla al inicio.
• Configurar CB_MCP_OAUTH_MCP_BASE_URL adicionalmente publica Metadatos de Recurso Protegido RFC 9728 para que los clientes conscientes de PRM puedan descubrir el servidor de autorización.
• El acceso está controlado por dos ámbitos leídos del claim scope/scp del token: couchbase-mcp:read (herramientas de lectura, incluyendo SQL++) y couchbase-mcp:write (herramientas de mutación KV). El acceso completo requiere 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 detalles completos, consulta la documentación.

Imagen Docker

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

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

Construyendo 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 puede ejecutarse utilizando variables de entorno 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 del Cliente MCP

La imagen Docker puede utilizarse 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 Couchbase se está ejecutando en la misma máquina host, en otro contenedor Docker o en un host remoto. Si su servidor Couchbase se ejecuta en su máquina host, su cadena de conexión probablemente tendría la forma couchbase://host.docker.internal. Para más detalles, consulte la documentación de docker.
• Puede especificar la red del contenedor usando la opción --network=<your_network>. La red que elija depende de su entorno; la predeterminada es bridge. Para más detalles, consulte controladores de red en docker.

Riesgos Asociados con los LLMs

• El uso de modelos de lenguaje grandes y tecnología similar implica riesgos, incluyendo la posibilidad de resultados inexactos o perjudiciales.
• Couchbase no revisa ni evalúa la calidad o precisión de dichos resultados, y estos pueden no reflejar las opiniones de Couchbase.
• Usted es el único responsable de determinar si utiliza modelos de lenguaje grandes y tecnología relacionada, y de cumplir con los términos de licencia, condiciones de uso y las políticas de su organización que rigen su uso.

Consejos para Solución de Problemas

• Asegúrese de que la ruta a su repositorio del servidor MCP sea correcta en la configuración si lo ejecuta desde el código fuente.
• Verifique que su cadena de conexión de Couchbase, nombre de usuario de la base de datos, contraseña o la ruta a los certificados sean correctos.
• Si utiliza Couchbase Capella, asegúrese de que el clúster sea accesible desde la máquina donde se ejecuta el servidor MCP.
• Compruebe que el usuario de la base de datos tenga los permisos adecuados para acceder al menos a un bucket.
• Confirme que el gestor de paquetes uv esté correctamente instalado y accesible. Puede que necesite proporcionar la ruta absoluta a uv/uvx en el campo command de la configuración.
• Revise los registros en busca de errores o advertencias que puedan indicar problemas con el servidor MCP. La ubicación de los registros depende de su cliente MCP.
• Si observa problemas al ejecutar su servidor MCP desde el código fuente después de actualizar su repositorio local del servidor MCP, intente 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 pueden invocarse contra un clúster Couchbase de demostración.

1. Exportar 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. Ejecutar las pruebas:

uv run pytest tests/ -v

👩‍💻 Contribuciones

¡Agradecemos las contribuciones de la comunidad! Ya sea que desee corregir errores, añadir funcionalidades o mejorar la documentación, su ayuda es bienvenida.

Si necesita ayuda, ha encontrado un error o desea contribuir con mejoras, el mejor lugar para hacerlo es aquí mismo — abriendo un issue en GitHub.

Para Desarrolladores

Si está interesado en contribuir con código o configurar un entorno de desarrollo:

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

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

Inicio 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 Soporte

¡Apreciamos sinceramente su 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 supervisan y mantienen activamente este repositorio e intentarán resolver los problemas con el mayor esfuerzo posible.

Nuestro portal de soporte no puede asistir con solicitudes relacionadas con este proyecto, por lo que le pedimos amablemente que todas las consultas se mantengan dentro de GitHub.

Su colaboración nos ayuda a todos a avanzar juntos — ¡gracias!