servidor mcp motherduck

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)

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

Instale Cursor desde cursor.com/downloads si aún no lo ha hecho
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:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

Uso con VS Code

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) .

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "motherduck_token",
        "description": "MotherDuck Token",
        "password": true
      }
    ],
    "servers": {
      "motherduck": {
        "command": "uvx",
        "args": [
          "mcp-server-motherduck",
          "--db-path",
          "md:",
          "--motherduck-token",
          "${input:motherduck_token}"
        ]
      }
    }
  }
}

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

{
  "inputs": [
    {
      "type": "promptString",
      "id": "motherduck_token",
      "description": "MotherDuck Token",
      "password": true
    }
  ],
  "servers": {
    "motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "${input:motherduck_token}"
      ]
    }
  }
}

Uso con Claude Desktop

Instale Claude Desktop desde claude.ai/download si aún no lo ha hecho
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 :

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_READ_SCALING_TOKEN_HERE>",
        "--saas-mode"
      ]
    }
  }
}

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:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

Archivo DuckDB local:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db"
      ]
    }
  }
}

Archivo DuckDB local en modo de solo lectura :

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db",
        "--read-only"
      ]
    }
  }
}

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 :

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>
Base de datos específica de MotherDuck :
uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
Base de datos local de DuckDB :
uvx mcp-server-motherduck --db-path /path/to/your/local.db
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:

npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"

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:

 {
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/local/mcp-server-motherduck",
        "run",
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Un servidor MCP para MotherDuck y DuckDB local.

Related Resources

Reddit Discussion about this server

Related MCP Servers

mcp-server-duckdb
ktanaka101
-
security
A
license
-
quality
A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools. It would be interesting to have LLM analyze it. DuckDB is suitable for local analysis.
Last updated -
5
105
Python
MIT License
Duck Duck MCP
qwang07
-
security
A
license
-
quality
This MCP server utilizes DuckDuckGo for web searches, providing structured search results with metadata and features like smart content classification and language detection, facilitating easy integration with AI clients supporting the MCP protocol.
Last updated -
1
25
1
JavaScript
MIT License
DuckDuckGo MCP Server
nickclyde
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.
Last updated -
2
26
Python
MIT License
DBHub
bytebase
-
security
A
license
-
quality
Universal database MCP server connecting to MySQL, PostgreSQL, SQLite, DuckDB and etc.
Last updated -
3
548
TypeScript
MIT License

View all related MCP servers

Appeared in Searches

Guide to Accessing a Self-Hosted Appwrite Instance

mcp-server-motherduck