Servidor MCP de Couchbase

Una implementación de servidor MCP de Couchbase que permite a los LLM interactuar directamente con los clústeres de Couchbase.

Características

Obtenga una lista de todos los ámbitos y colecciones en el depósito especificado
Obtener la estructura para una colección
Obtener un documento por ID de un alcance y colección específicos
Insertar un documento por ID en un alcance y colección específicos
Eliminar un documento por ID de un ámbito y una colección específicos
Ejecutar una consulta SQL++ en un ámbito específico
- Hay una opción en el servidor MCP, READ_ONLY_QUERY_MODE que se establece en verdadero por defecto para deshabilitar la ejecución de consultas SQL++ que modifiquen los datos o la estructura de la colección subyacente. Tenga en cuenta que los documentos aún se pueden actualizar por ID.

Prerrequisitos

Python 3.10 o superior.
Un clúster de Couchbase en ejecución. La forma más sencilla de empezar es usar la versión gratuita de Capella , que es una versión totalmente administrada del servidor 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.
Se instaló un cliente MCP como Claude Desktop para conectar el servidor a Claude. Se proporcionan instrucciones para Claude Desktop y Cursor. También se pueden usar otros clientes MCP.

Configuración

Clona el repositorio en tu máquina local.

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

Configuración del servidor 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",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

El servidor se puede configurar mediante variables de entorno. Se admiten las siguientes variables:

CB_CONNECTION_STRING : La cadena de conexión al clúster Couchbase
CB_USERNAME : El nombre de usuario con acceso al depósito que se utilizará para conectarse
CB_PASSWORD : La contraseña para el nombre de usuario para conectarse
CB_BUCKET_NAME : El nombre del depósito al que accederá el servidor
READ_ONLY_QUERY_MODE : Esta opción permite configurar si se permiten las consultas SQL++ que permiten modificar datos. Su valor predeterminado es "Verdadero".
path/to/cloned/repo/mcp-server-couchbase/ debe ser la ruta al repositorio clonado en tu equipo local. ¡No olvides la barra diagonal final!

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

Escritorio de Claude

Siga los pasos a continuación para utilizar el servidor Couchbase MCP con el cliente Claude Desktop MCP

Ahora es posible agregar el servidor MCP a Claude Desktop editando el archivo de configuración. Encontrará instrucciones más detalladas en la guía de inicio rápido de MCP .
- En Mac, el archivo de configuración se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows, el archivo de configuración se encuentra en %APPDATA%\Claude\claude_desktop_config.json
Abra el archivo de configuración y agregue la configuración a la sección mcpServers .
Reinicie Claude Desktop para aplicar los cambios.
Ahora puede utilizar el servidor en Claude Desktop para ejecutar consultas en el clúster Couchbase utilizando lenguaje natural y realizar operaciones CRUD en documentos.

Registros del escritorio de Claude

Los registros de Claude Desktop se pueden encontrar en las siguientes ubicaciones:

MacOS: ~/Biblioteca/Registros/Claude
Windows: %APPDATA%\Claude\Registros

Los registros se pueden usar para diagnosticar problemas de conexión u otros problemas con la configuración del servidor MCP. Para más información, consulte la documentación oficial .

Cursor

Siga los pasos a continuación para utilizar el servidor Couchbase MCP con Cursor:

Instale Cursor en su máquina.
En Cursor, vaya a Cursor > Configuración del cursor > MCP > Agregar un nuevo servidor MCP global. Consulte también la documentación sobre cómo configurar el servidor MCP desde Cursor.
Especifique la misma configuración . Es posible que deba agregar la configuración del servidor bajo una clave principal de mcpServers.
Guardar la configuración.
Verás que Couchbase se ha añadido a la lista de servidores de MCP. Actualiza para comprobar si el servidor está habilitado.
Ahora puede utilizar el servidor Couchbase MCP en Cursor para consultar su clúster Couchbase usando lenguaje natural y realizar operaciones CRUD en documentos.

Para obtener más detalles sobre la integración de MCP con Cursor, consulte la documentación oficial de Cursor MCP .

Registros del cursor

En el panel inferior de Cursor, haga clic en "Salida" y seleccione "Cursor MCP" en el menú desplegable para ver los registros del servidor. Esto puede ayudar a diagnosticar problemas de conexión u otros problemas con la configuración del servidor MCP.

Editor de windsurf

Siga los pasos a continuación para utilizar el servidor Couchbase MCP con Windsurf Editor .

Instale Windsurf Editor en su máquina.
En el Editor Windsurf, vaya a la Paleta de Comandos > Panel de Configuración MCP de Windsurf o a Windsurf - Configuración > Avanzado > Cascada > Servidores de Protocolo de Contexto de Modelo (MCP). Para más detalles sobre la configuración, consulte la documentación oficial .
Haga clic en "Agregar servidor" y luego en "Agregar servidor personalizado". En la configuración que se abre en el editor, agregue la configuración del servidor Couchbase MCP mencionada anteriormente.
Guardar la configuración.
Verás que Couchbase se ha añadido a la lista de servidores MCP, en Configuración avanzada. Actualiza la aplicación para comprobar si el servidor está habilitado.
Ahora puede utilizar el servidor Couchbase MCP en Windsurf Editor para consultar su clúster Couchbase usando lenguaje natural y realizar operaciones CRUD en documentos.

Para obtener más detalles sobre la integración de MCP con Windsurf Editor, consulte la documentación oficial de Windsurf MCP .

Modo de servidor SSE

Existe una opción para ejecutar el servidor MCP en modo de transporte de eventos enviados por el servidor (SSE) .

Uso

De forma predeterminada, el servidor MCP se ejecutará en el puerto 8080, pero esto se puede configurar mediante la variable de entorno FASTMCP_PORT .

uv run src/mcp_server.py --connection-string='<string_connection_string>' --username='<username_database>' --password='<contraseña_database>' --bucket-name='<bucket_couchbase_to_use>' --read-only-query-mode=true --transport=sse

El servidor estará disponible en http://localhost:8080/sse . Esto se puede usar en clientes MCP compatibles con el modo de transporte SSE.

Imagen de Docker

El servidor MCP también se puede compilar y ejecutar como un contenedor Docker. Las imágenes precompiladas se pueden encontrar en DockerHub .

docker built -t mcp/couchbase .

Correr

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

docker run -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

Riesgos asociados con los LLM

El uso de modelos lingüísticos de gran tamaño y tecnologías similares implica riesgos, incluida la posibilidad de obtener 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 determinar si utilizará modelos de lenguaje grandes y tecnología relacionada, y de cumplir con los términos de licencia, los términos de uso y las políticas de su organización que rigen su uso de los mismos.

Servidor MCP administrado

El servidor Couchbase MCP también se puede utilizar como servidor administrado en sus aplicaciones de agente a través de Smithery.ai .

Consejos para la solución de problemas

Asegúrese de que la ruta al repositorio de su servidor MCP sea correcta en la configuración.
Verifique que la cadena de conexión de Couchbase, el nombre de usuario de la base de datos, la contraseña y el nombre del depósito 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.
Verifique que el usuario de la base de datos tenga los permisos adecuados para acceder al depósito especificado.
Confirme que el administrador de paquetes uv esté correctamente instalado y sea accesible. Es posible que deba proporcionar la ruta absoluta a uv en el campo command de la configuración.
Revise los registros para detectar errores o advertencias que puedan indicar problemas con el servidor MCP. Los registros del servidor se encuentran bajo el nombre mcp-server-couchbase.log .

📢 Política de soporte

¡Realmente apreciamos su interés en este proyecto!
Este proyecto es mantenido por la comunidad , lo que significa que no cuenta con el respaldo oficial de nuestro equipo de soporte.

Si necesita ayuda, ha encontrado un error o desea contribuir con mejoras, el mejor lugar para hacerlo es aquí: abriendo un problema en GitHub .
Nuestro portal de soporte no puede ayudar con solicitudes relacionadas con este proyecto, por lo que le solicitamos que todas las consultas permanezcan dentro de GitHub.

Tu colaboración nos ayuda a todos a avanzar juntos. ¡Gracias!

Couchbase MCP Server

Integrations