Servidor MCP DuckDB de MotherDuck

Una implementación de servidor MCP que interactúa con las bases de datos DuckDB y MotherDuck, proporcionando capacidades de análisis SQL a los asistentes de IA y las IDE.

Recursos

• Cerrar el ciclo: Canalizaciones de datos más rápidas con MCP, DuckDB e IA (publicación de blog)

• Desarrollo más rápido de canalizaciones de datos con MCP y DuckDB (YouTube)

Related MCP server: Duck Duck MCP

Características

• Ejecución híbrida : consulta datos de bases de datos locales de DuckDB o MotherDuck basadas en la nube

• Integración de almacenamiento en la nube : acceda a los datos almacenados en Amazon S3 u otro almacenamiento en la nube gracias a las integraciones de MotherDuck

• Intercambio de datos : crear y compartir bases de datos

• Análisis SQL : utilice el dialecto SQL de DuckDB para consultar cualquier tamaño de datos directamente desde su Asistente de IA o IDE

• Arquitectura sin servidor : ejecute análisis sin necesidad de configurar instancias o clústeres

Componentes

Indicaciones

El servidor proporciona un mensaje:

• duckdb-motherduck-initial-prompt : un mensaje para inicializar una conexión a DuckDB o MotherDuck y comenzar a trabajar con él

Herramientas

El servidor ofrece una herramienta:

• query : ejecuta una consulta SQL en la base de datos DuckDB o MotherDuck

  • Entradas :

    • query (cadena, obligatoria): La consulta SQL a ejecutar

Todas las interacciones con DuckDB y MotherDuck se realizan mediante la escritura de consultas SQL.

Empezando

Requisitos generales

• uv instalado, puedes instalarlo usando pip install uv o brew install uv

Si planea utilizar el MCP con Claude Desktop o cualquier otro cliente compatible con MCP, es necesario instalar el cliente.

Requisitos previos para DuckDB

• No hay requisitos previos. El servidor MCP puede crear una base de datos en memoria sobre la marcha.

• O conéctese a un archivo de base de datos DuckDB local existente o a uno almacenado en un almacenamiento de objetos remoto (por ejemplo, AWS S3).

Consulte Conectarse a DuckDB local .

Requisitos previos para MotherDuck

• Regístrese para obtener una cuenta de MotherDuck

• Generar un token de acceso a través de la interfaz de usuario de MotherDuck

• Almacene el token de forma segura para usarlo en la configuración

Uso con cursor

1. Instale Cursor desde cursor.com/downloads si aún no lo ha hecho

2. Cursor abierto:

• Para configurarlo globalmente por primera vez, vaya a Configuración->MCP y haga clic en "+ Agregar nuevo servidor MCP global".

• Esto abrirá un archivo mcp.json al que agregarás la siguiente configuración:

Uso con VS Code

1. Para una instalación más rápida, haga clic en uno de los botones "Instalar con UV" en la parte superior de este README.

Instalación manual

Agrega el siguiente bloque JSON a tu archivo de configuración de usuario (JSON) en VS Code. Para ello, presiona Ctrl + Shift + P y escribe Preferences: Open User Settings (JSON) .

Opcionalmente, puede agregarlo a un archivo llamado .vscode/mcp.json en su espacio de trabajo. Esto le permitirá compartir la configuración con otros.

Uso con Claude Desktop

1. Instale Claude Desktop desde claude.ai/download si aún no lo ha hecho

2. Abra el archivo de configuración de Claude Desktop:

• Para acceder rápidamente o crearlo por primera vez, abra la aplicación Claude Desktop, seleccione Configuración y haga clic en la pestaña "Desarrollador", finalmente haga clic en el botón "Editar configuración".

• Agregue la siguiente configuración a su claude_desktop_config.json :

Notas importantes :

• Reemplace YOUR_MOTHERDUCK_TOKEN_HERE con su token MotherDuck real

• Reemplace YOUR_HOME_FOLDER_PATH con la ruta a su directorio personal (necesaria para DuckDB para las operaciones con archivos). Por ejemplo, en macOS, sería /Users/your_username

• La variable de entorno HOME es necesaria para que DuckDB funcione correctamente.

Cómo proteger su servidor MCP al consultar MotherDuck

Si el servidor MCP está expuesto a terceros y solo debe tener acceso de lectura a los datos, recomendamos utilizar un token de escalamiento de lectura y ejecutar el servidor MCP en modo SaaS.

Los tokens de escalado de lectura son tokens de acceso especiales que permiten operaciones de lectura escalables al permitir hasta cuatro réplicas de lectura simultáneas, lo que mejora el rendimiento para múltiples usuarios finales y limita las capacidades de escritura . Consulte la documentación de escalado de lectura para aprender a crear un token de escalado de lectura.

El Modo SaaS de MotherDuck mejora la seguridad al restringir el acceso a archivos, bases de datos, extensiones y configuraciones locales, lo que lo hace ideal para herramientas de terceros que requieren una protección del entorno más estricta. Obtenga más información en la documentación del Modo SaaS .

Configuración segura

Conectarse a DuckDB local

Para conectarse a un DuckDB local, en lugar de utilizar el token MotherDuck, especifique la ruta a su archivo de base de datos DuckDB local o utilice :memory: para una base de datos en memoria.

Base de datos en memoria:

Archivo DuckDB local:

Archivo DuckDB local en modo de solo lectura :

Nota : El modo de solo lectura para conexiones locales de DuckDB con respaldo de archivos también utiliza conexiones de corta duración. Cada vez que se utiliza la herramienta de consulta MCP, se crea una conexión temporal de solo lectura, se ejecuta la consulta y se cierra la conexión. Esta función surgió de un flujo de trabajo donde DBT se utilizaba para modelar datos dentro de DuckDB y, posteriormente, un cliente MCP (Windsurf/Cline/Claude/Cursor) se utilizaba para explorar la base de datos. Las conexiones de corta duración permiten que cada herramienta se ejecute y luego libere su conexión, permitiendo que la siguiente se conecte.

Consultas de ejemplo

Una vez configurado, puedes, por ejemplo, pedirle a Claude que ejecute consultas como:

• "Crear una nueva base de datos y tabla en MotherDuck"

• Consultar datos de mi archivo CSV local

• Unir datos de mi base de datos local DuckDB con una tabla en MotherDuck

• Analizar datos almacenados en Amazon S3

Pruebas

El servidor está diseñado para ejecutarse con herramientas como Claude Desktop y Cursor, pero puede iniciarlo manualmente para realizar pruebas. Al probar el servidor manualmente, puede especificar la base de datos a la que conectarse mediante el parámetro --db-path :

1. Base de datos MotherDuck predeterminada :

   • Para conectarse a la base de datos MotherDuck predeterminada, deberá pasar el token de autenticación mediante el parámetro --motherduck-token .

   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>

2. Base de datos específica de MotherDuck :

   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>

3. Base de datos local de DuckDB :

   uvx mcp-server-motherduck --db-path /path/to/your/local.db

4. Base de datos en memoria :

   uvx mcp-server-motherduck --db-path :memory:

Si no especifica una ruta de base de datos pero ha configurado la variable de entorno motherduck_token , el servidor se conectará automáticamente a la base de datos MotherDuck predeterminada ( md: ).

Ejecutando en modo SSE

El servidor también podría estar ejecutando el modo SSE usando supergateway ejecutando el siguiente comando:

Además, puede apuntar a sus clientes, como Claude Desktop o Cursor, a este punto final.

Configuración de desarrollo

Para ejecutar el servidor desde un entorno de desarrollo local, utilice la siguiente configuración:

Solución de problemas

• Si tiene problemas de conexión, verifique que su token MotherDuck sea correcto

• Para problemas de acceso a archivos locales, asegúrese de que el parámetro --home-dir esté configurado correctamente

• Verifique que el comando uvx esté disponible en su PATH

• Si encuentra errores spawn uvx ENOENT , intente especificar la ruta completa a uvx ( which uvx )

• En la versión anterior v0.4.0 usábamos variables de entorno, ahora usamos parámetros

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.