MotherDuck MCP Server

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 de MotherDuck Remote MCP

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 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.
• Solo lectura en 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: Instalar 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"]
    }
  }
}

Flexibilidad total 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 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ía de despliegue, y Solución de Problemas si encuentras inconvenientes.

Configuración del Cliente

Cliente	Ubicación de Configuración	Instalación en Un Clic
Claude Desktop	Ajustes → Desarrollador → Editar Configuración	.mcpb (MCP Bundle)
Claude Code	Usa los comandos CLI abajo	-
Codex CLI	Usa los comandos CLI abajo o ~/.codex/config.toml	-
Gemini CLI	Usa los comandos CLI 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 la bandera --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 Remote MCP — 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 Asegurando DuckDB para las opciones disponibles.

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