MotherDuck

Servidor MCP Local de DuckDB / MotherDuck

Analítica SQL e ingeniería de datos para Asistentes de IA e IDEs.

Conecta asistentes de IA a tus datos usando el potente motor SQL analítico de DuckDB. Soporta conexión a archivos DuckDB locales, bases de datos en memoria, bases de datos alojadas en S3 y MotherDuck. Permite ejecutar consultas SQL de lectura y escritura, explorar catálogos de bases de datos y cambiar entre diferentes conexiones de base de datos sobre la marcha.

¿Buscas un servidor MCP remoto completamente gestionado para MotherDuck? → Ir a la documentación del MCP Remoto de MotherDuck

MCP Remoto vs Local

📝 ¿Migrando desde v0.x?

• Solo lectura por defecto: El servidor ahora se ejecuta en modo solo lectura por defecto. Añade --read-write para habilitar el acceso de escritura. Consulta Asegurando para Producción.
• Base de datos por defecto cambiada: El valor por defecto de --db-path cambió de md: a :memory:. Añade --db-path md: explícitamente para MotherDuck.
• El modo solo lectura de MotherDuck requiere token de escalado de lectura: Las conexiones a MotherDuck en modo solo lectura requieren un token de escalado de lectura. Los tokens regulares requieren --read-write.

Inicio Rápido

Prerrequisitos: Instala uv vía pip install uv o brew install uv

Conectando a DuckDB en Memoria (Modo Desarrollo)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Máxima flexibilidad sin restricciones — acceso de lectura-escritura y la capacidad de cambiar a cualquier base de datos (archivos locales, S3 o MotherDuck) en tiempo de ejecución.

Conectando a un Archivo DuckDB Local en Modo Solo Lectura

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

Se conecta a un archivo DuckDB específico en modo solo lectura. No retendrá el bloqueo del archivo, por lo que es conveniente usarlo junto con una conexión de escritura al mismo archivo DuckDB. También puedes conectarte a archivos DuckDB remotos en S3 usando s3://bucket/path.duckdb — consulta Variables de Entorno para la autenticación de S3. Si estás considerando el acceso de terceros al MCP, consulta Asegurando para Producción.

Conectando a MotherDuck en Modo Lectura-Escritura

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Consulta Parámetros de Línea de Comandos para más opciones, Asegurando para Producción para guías de despliegue, y Solución de Problemas si encuentras incidencias.

Configuración del Cliente

Cliente	Ubicación de Configuración	Instalación en Un Clic
Claude Desktop	Ajustes → Desarrollador → Editar Configuración	.mcpb (Paquete MCP)
Claude Code	Usa los comandos CLI de abajo	-
Codex CLI	Usa los comandos CLI de abajo o ~/.codex/config.toml	-
Gemini CLI	Usa los comandos CLI de abajo o ~/.gemini/settings.json	-
Cursor	Ajustes → MCP → Añadir nuevo servidor MCP global
VS Code	Ctrl+Shift+P → "Preferencias: Abrir Configuración de Usuario (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) o .kiro/settings/mcp.json (proyecto)

Cualquier cliente compatible con MCP puede usar este servidor. Añade la configuración JSON de Inicio Rápido al archivo de configuración MCP de tu cliente. Consulta la documentación de tu cliente para la ubicación del archivo de configuración.

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Herramientas

*Requiere el flag --allow-switch-databases

Todas las herramientas devuelven JSON. Los resultados están limitados a 1024 filas / 50,000 caracteres por defecto (configurable vía --max-rows, --max-chars).

Asegurando para Producción

Al dar acceso a terceros a un servidor MCP autoalojado, el modo solo lectura por sí solo no es suficiente — aún permite el acceso al sistema de archivos local, cambiar configuraciones de DuckDB y otras operaciones potencialmente sensibles.

Para despliegues en producción con acceso de terceros, recomendamos MotherDuck MCP Remoto — sin configuración, con capacidad de lectura-escritura y alojado por MotherDuck.

Autoalojando MotherDuck MCP: Haz un fork de este repositorio y personalízalo según sea necesario. Usa una cuenta de servicio con tokens de escalado de lectura y habilita el modo SaaS para restringir el acceso a archivos locales.

Autoalojando DuckDB MCP: Usa --init-sql para aplicar configuraciones de seguridad. Consulta la guía de seguridad de DuckDB para las opciones disponibles.

Docker

Construye y ejecuta el servidor con HTTP Transmisible en el puerto 8000 (por defecto usa un DuckDB en memoria):

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

Conéctate a MotherDuck pasando un token y sobrescribiendo el comando:

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

El endpoint MCP está disponible en http://localhost:8000/mcp. Los flags de CLI y variables de entorno de abajo siguen siendo aplicables.

Parámetros de Línea de Comandos

Variables de Entorno

Solución de Problemas

• spawn uvx ENOENT: Especifica la ruta completa a uvx (ejecuta which uvx para encontrarlo)
• Archivo bloqueado: Asegúrate de que --ephemeral-connections esté activado (por defecto: true) y de que no estés conectado en modo lectura-escritura

Recursos

• Documentación de MotherDuck MCP
• Cierra el Ciclo: Pipelines de Datos Más Rápidos con MCP, DuckDB e IA (Blog)
• Pipelines de Datos Más Rápidos con MCP y DuckDB (YouTube)

Desarrollo

Para ejecutar desde el código fuente:

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Proceso de Lanzamiento

1. Ejecuta la GitHub Action Release New Version
2. Introduce la versión en formato MAJOR.MINOR.PATCH
3. El flujo de trabajo incrementa la versión, publica en PyPI/registro MCP y crea el lanzamiento en GitHub con el paquete MCPB

Licencia

Licencia MIT - consulta el archivo LICENSE.

mcp-name: io.github.motherduckdb/mcp-server-motherduck