Couchbase

Servidor MCP de Couchbase

El Servidor MCP de Couchbase es un servidor autoalojado de Model Context Protocol (MCP) que conecta agentes de IA y asistentes impulsados por LLM — Claude, Cursor, Windsurf, VS Code Copilot y otros clientes MCP — con datos en clústeres de Couchbase, ya sea alojados en Capella o autogestionados. MCP es un estándar abierto que permite a los asistentes de IA llamar herramientas y consultar fuentes de datos externas; este servidor implementa ese estándar para Couchbase, de modo que un agente de IA pueda inspeccionar tu clúster, ejecutar consultas SQL++, leer y escribir documentos, y analizar el rendimiento de las consultas usando lenguaje natural en lugar de código escrito a mano.

Proporciona herramientas en categorías que incluyen Salud del Clúster, Esquema de Datos, Clave-Valor, Consulta y Rendimiento — con controles de seguridad mediante el modo de solo lectura (activado por defecto) y la desactivación fina de herramientas, para que puedas permitir que un agente de IA explore y consulte tus datos sin arriesgar escrituras no intencionadas. Admite transportes STDIO y HTTP Streamable.

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

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

Para documentación completa, visita docs.couchbase.com/mcp-server.

Tabla de Contenidos

• Por qué el Servidor MCP de Couchbase
• Ejemplos de Prompts
• Características/Herramientas
• Requisitos Previos
• Configuración
• Servidor de Información Operativa
• Modo de Transporte HTTP Streamable
• Modo de Transporte SSE
• Autorización OAuth 2.1
• Imagen Docker
• Recopilación de Datos de Uso
• Consejos de Solución de Problemas
• Pruebas de Integración
• Preguntas Frecuentes
• Contribuciones
• Política de Soporte

Por qué el Servidor MCP de Couchbase

• Seguro por defecto — las operaciones de escritura (upserts/inserciones/eliminaciones de documentos y consultas SQL++ que modifican datos) están bloqueadas a menos que establezcas explícitamente CB_MCP_READ_ONLY_MODE=false, y las herramientas individuales pueden desactivarse o protegerse tras la confirmación del usuario.
• Funciona con Capella y clústeres autogestionados — la misma configuración se conecta a Couchbase Capella (totalmente gestionado) o a un clúster de Couchbase Server autoalojado.
• Consciente de RBAC — la desactivación de herramientas es una capa de conveniencia para guiar el comportamiento del LLM; el control de acceso basado en roles del usuario subyacente de Couchbase sigue siendo el límite de seguridad autoritativo.
• Transportes de producción — ejecútalo sobre STDIO para clientes de escritorio locales, o HTTP Streamable con OAuth 2.1 opcional (JWT/JWKS, independiente del proveedor — Auth0, Okta, Keycloak, Entra, Cognito, etc.) para despliegues compartidos/remotos.
• Cualquier cliente MCP — probado con Claude Desktop, Cursor, Windsurf, VS Code y JetBrains AI Assistant/Junie; funciona con cualquier cliente que implemente la especificación MCP.

Ejemplos de Prompts

Una vez que el servidor esté conectado, puedes hablar con tu clúster de Couchbase en lenguaje natural a través de tu asistente de IA. Por ejemplo:

• "¿Qué buckets, scopes y colecciones tengo en este clúster, y cuál es el esquema de la colección orders?"
• "Ejecuta una consulta SQL++ para encontrar los 10 documentos más recientes en la colección users where status = 'active'."
• "¿Cuáles son las 5 consultas más lentas en este clúster en la última hora, y alguna de ellas carece de un índice de cobertura?"
• "Comprueba si este clúster está sano y dime qué servicios están en ejecución."
• "Inserta un nuevo documento en la colección products con estos campos: ..." (requiere CB_MCP_READ_ONLY_MODE=false)

Características/Herramientas

Esta distribución incluye dos servidores: el servidor operativo (por defecto — las tablas inmediatamente siguientes) se comunica con un clúster de Couchbase regular mediante el SDK couchbase, y el servidor Operational Insights (su propia tabla más abajo) se comunica con clústeres de Operational Insights mediante el SDK couchbase-operational-insights.

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 búsqueda de texto completo (FTS)

Requiere Couchbase Server 7.6+ y el servicio Search. La búsqueda vectorial no es compatible con estas herramientas (consulta las herramientas de búsqueda vectorial por separado).

Herramientas de análisis de rendimiento de consultas

Herramientas de Operational Insights

Registradas por el servidor operational-insights separado (consulta Servidor de Información Operativa más abajo), no por el servidor operational predeterminado.

Las herramientas de la API de Solicitud Asíncrona del Servidor forman un flujo de inicio → sondeo → descartar-o-cancelar para consultas de larga duración: run_query_async devuelve un query_handle, get_async_query_results se sondea hasta que informa que está lista (y devuelve las filas), luego discard_async_query_results libera los resultados o, para una consulta aún en ejecución, cancel_async_query la detiene.

Nota: get_collections_in_scope, get_schema_for_collection, create_index y list_indexes existen, con comportamiento diferente, en ambos servidores. (get_server_configuration_status también aparece en ambos, pero es deliberadamente una herramienta compartida — misma implementación, misma forma de resultado — por lo que no necesita desambiguación.) Cada servidor es un proceso separado, por lo que esto solo es una preocupación si un solo cliente MCP registra tanto operational como operational-insights simultáneamente — en ese caso, desambigüe en la capa de configuración del cliente (por ejemplo, dando a las dos entradas del servidor nombres distintos en la configuración del propio cliente).

Requisitos previos

• Python 3.10 o superior.
• Un clúster de Couchbase en ejecución. La forma más fácil de comenzar es usar el nivel gratuito de Capella, que es la versión totalmente administrada del servidor de Couchbase. Puede seguir las instrucciones para importar uno de los conjuntos de datos de muestra o importar los suyos propios.
• 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 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 agregarlo 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 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 scopes/colecciones y gestión de índices) están deshabilitadas. Todas las herramientas de escritura (KV: upsert, insert, replace, delete, mutación de sub-documentos; gestión de scopes/colecciones: create_scope, create_collection, delete_scope, delete_collection; gestión 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: Todas las herramientas de escritura se cargan y se permiten las consultas de modificación de datos/estructura SQL++.

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

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 usará para validar los certificados del servidor. Si se especifican tanto la ruta del Certificado de cliente y la Clave como el nombre de usuario y la contraseña, los certificados de cliente se usarán para la autenticación.

Deshabilitar herramientas

Puede desactivar herramientas específicas para evitar que se carguen y se 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 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: Desactivar 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 desactiva 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é establecido en 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: Configure siempre permisos RBAC apropiados en sus credenciales de usuario de Couchbase como medida de seguridad principal. Use la desactivació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 de Herramientas

Puede requerir confirmación explícita del usuario para herramientas específicas antes de la ejecución (cuando el cliente MCP admita la obtenció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, comentarios # admitidos)

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 la obtención, se solicita al usuario que confirme.
• Si el cliente no admite la obtención, la herramienta se ejecuta sin confirmación por compatibilidad con versiones anteriores.

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

uvx couchbase-mcp-server --version

Registro (Logging)

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 desactiva todo el registro.
• CB_MCP_LOG_SINKS — 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 establecen. Un tamaño de 0 (global o por nivel) no es válido y vuelve al predeterminado (1 MB) con una advertencia de inicio. CB_MCP_LOG_MAX_BYTES (bytes) está obsoleto pero aún se respeta por compatibilidad con versiones anteriores; se ignora cuando CB_MCP_LOG_ROTATION_MAX_SIZE_MB también está establecido, e imprime una advertencia de obsolescencia al inicio.
• Retención — CB_MCP_LOG_RETENTION_BACKUP_COUNT establece cuántas copias de seguridad rotadas 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 establecen. Establezca un conteo a 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

Servidor de Información Operativa

Junto al servidor operational predeterminado (el que cada sección anterior describe), esta distribución incluye un segundo servidor para clústeres de Información Operativa, usando el SDK separado couchbase-operational-insights. Es un producto diferente de un clúster regular de Couchbase y se ejecuta como un proceso independiente en su propio puerto.

Ejecútelo pasando operational-insights como subcomando de CLI (o agregándolo como el comando del contenedor):

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 es una URL HTTP(S), no una cadena de conexión couchbase:// — p. ej., http://localhost:8095 para un servidor local de Información Operativa, o https://<host>:18095 para Capella. Este es el error de configuración más común al apuntar este servidor a un clúster.

Cada otra bandera (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) es idéntica a la del servidor operativo; consulte Configuración adicional para el servidor MCP — excepto los valores predeterminados para puerto (8001, no 8000) y archivo de registro (mcp_server_operational_insights.log, no mcp_server.log), ya que dos servidores no pueden compartir ninguno de ellos. OAuth utiliza las mismas etiquetas de alcance (couchbase-mcp:read / couchbase-mcp:write) que el servidor operativo, por lo que una configuración de IdP existente funciona para ambos sin cambios.

Ejemplo de configuración 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"
      }
    }
  }
}

Consulte Herramientas de Operational Insights arriba para la lista de herramientas, y la nota allí sobre los tres nombres de herramientas compartidos con el servidor operativo.

Ambos servidores comparten una única lista del Registro MCP, io.github.couchbase/mcp-server-couchbase, publicada desde server.json. La lista tiene una entrada de paquete separada para cada servidor (PyPI y Docker). Cada entrada pasa su subcomando (operational o operational-insights) y declara solo los argumentos y variables de entorno de ese servidor.

Modo de transporte HTTP Streamable

El servidor MCP puede ejecutarse en modo de transporte HTTP Streamable, que permite que múltiples clientes se conecten a la misma instancia del servidor a través de HTTP. Verifique si su cliente MCP admite el transporte HTTP streamable antes de intentar conectarse al servidor MCP en este modo.

Nota: La autorización OAuth 2.1 es compatible con este transporte. Consulte 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 admitan el modo de transporte HTTP streamable, 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 Server-Sent Events (SSE).

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

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 admitan 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 su 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_* enumeradas en Configuración adicional:

• OAuth se activa solo cuando las tres de CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER y CB_MCP_OAUTH_JWT_AUDIENCE están establecidas; establecer solo algunas de ellas falla al inicio.
• Establecer CB_MCP_OAUTH_MCP_BASE_URL además 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 de la declaración scope/scp del token: couchbase-mcp:read (herramientas de lectura, incluido SQL++) y couchbase-mcp:write (herramientas de escritura: mutaciones KV, gestión de alcances/colecciones y gestión de índices). El acceso completo requiere ambos. Si su IdP no puede emitir esas etiquetas canónicas, anúlelas 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 más detalles, consulte 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 extraerse mediante docker pull docker.io/couchbase/mcp-server:latest.

Alternativamente, somos 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 del 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 Couchbase se ejecuta 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; el predeterminado es bridge. Para más detalles, consulte controladores de red en docker.

Riesgos asociados con los LLM

• El uso de modelos de lenguaje grandes y tecnología similar implica riesgos, incluido el potencial de resultados inexactos o dañinos.
• Couchbase no revisa ni evalúa la calidad o precisión de dichos resultados, y dichos resultados pueden no reflejar las opiniones de Couchbase.
• Usted es el único responsable de decidir si usar modelos de lenguaje grandes y tecnología relacionada, y de cumplir con cualquier término de licencia, términos de uso y las políticas de su organización que rigen su uso de los mismos.

Recopilació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 usted pueda proporcionar a Couchbase (como su 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 usted almacene en los productos de Couchbase. Usamos los Datos de uso para comprender patrones de uso agregados y hacer que nuestros productos sean más útiles para usted. Para obtener más información sobre cómo Couchbase recopila, protege y procesa la información, consulte la Política de Privacidad de Couchbase disponible en https://www.couchbase.com/privacy-policy.

Consejos para la resolución de problemas

• Asegúrese de que la ruta al repositorio de su servidor MCP sea correcta en la configuración si se 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 usa 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 administrador de paquetes uv esté instalado y sea accesible correctamente. Es posible que deba proporcionar la ruta absoluta a uv/uvx en el campo command en la configuración.
• Revise los registros para ver si hay 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 se pueden invocar contra un clúster de demostración de Couchbase.

1. Exporte 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)
   • Opcional, para las pruebas propias del servidor de Operational Insights: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Esas pruebas se omiten automáticamente (no fallan) cuando no están establecidas.
2. Ejecute las pruebas:

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

Preguntas frecuentes

¿Qué es el servidor MCP de Couchbase? Es una implementación autohospedada del Protocolo de Contexto de Modelo que permite a los asistentes y agentes de IA (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, y cualquier otro cliente MCP) consultar y, opcionalmente, modificar datos en un clúster de Couchbase usando lenguaje natural.

¿Cómo conecto Claude Desktop a Couchbase? Instale el servidor con uvx couchbase-mcp-server (o ejecútelo desde el código fuente o Docker), luego agregue su configuración al claude_desktop_config.json de Claude Desktop como se muestra en Configuración. Reinicie Claude Desktop y detectará las nuevas herramientas.

¿Puedo usar esto con Couchbase Capella? Sí. La misma configuración de CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (o certificado mTLS) funciona tanto para Couchbase Capella como para clústeres de Couchbase Server autogestionados.

¿Es seguro permitir que un agente de IA escriba en mi base de datos? Por defecto, CB_MCP_READ_ONLY_MODE es verdadero, por lo que todas las operaciones de escritura — upserts/inserciones/reemplazos/eliminaciones de documentos y declaraciones SQL++ que modifican datos — están deshabilitadas y las herramientas de escritura ni siquiera se cargan. También puede deshabilitar herramientas individuales (consulte Deshabilitar herramientas) o requerir confirmación explícita del usuario antes de que se ejecuten herramientas específicas (consulte Elicitación/Confirmación). Los controles a nivel de herramienta guían el comportamiento del LLM; los permisos RBAC de su usuario de Couchbase siguen siendo el límite de seguridad real.

¿Puedo ejecutar consultas en lenguaje natural contra mis datos sin escribir SQL++ yo mismo? Sí: haga una pregunta a su asistente de IA en inglés sencillo (por ejemplo, "muéstrame los 10 pedidos más recientes de más de $100") y puede traducirla a una consulta SQL++ usando la herramienta run_sql_plus_plus_query. También puede pedirle al asistente que explain_sql_plus_plus_query una consulta o pedir recomendaciones al asesor de índices. ¿Cuál es la diferencia entre el transporte STDIO, HTTP Streamable y SSE? STDIO es para un único cliente MCP local (por ejemplo, Claude Desktop) que inicia el servidor como un subproceso. HTTP Streamable permite que múltiples clientes compartan una única instancia de servidor en ejecución a través de HTTP, y admite OAuth 2.1. SSE es el transporte HTTP más antiguo, ahora obsoleto por la especificación MCP en favor de HTTP Streamable — consulte Modo de transporte HTTP Streamable.

¿Esto está soportado oficialmente por Couchbase? Este proyecto es mantenido por la comunidad de Couchbase — consulte Política de soporte. El soporte empresarial está disponible por separado a través de Couchbase AI Data Plane.

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 deseas contribuir con mejoras, el mejor lugar para hacerlo es aquí mismo — abriendo un issue en GitHub.

Para Desarrolladores

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

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

• 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 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 tu interés en este proyecto! Este proyecto es mantenido por la comunidad de Couchbase, lo que significa que no está soportado oficialmente por nuestro equipo de soporte. Sin embargo, nuestros ingenieros están monitoreando y manteniendo activamente este repositorio y 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 permanezcan dentro de GitHub.

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