MotherDuck

DuckDB / MotherDuck Local MCP Server

Analítica SQL y 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. Admite 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 bases de datos sobre la marcha.

¿Buscas un servidor MCP remoto totalmente gestionado para MotherDuck? → Ir a la documentación de MotherDuck Remote MCP

MCP remoto vs local

Inicio rápido

Requisitos previos: Instala uv mediante pip install uv o brew install uv

Conexión a DuckDB en memoria (modo de 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.

Conexión a un archivo DuckDB local en modo de 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 de solo lectura. No mantiene 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.

Conexión a MotherDuck en modo de 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 implementación y Solución de problemas si encuentras problemas.

Configuración del cliente

Cliente	Ubicación de configuración	Instalación con un clic
Claude Desktop	Configuración → Desarrollador → Editar configuración	.mcpb (MCP Bundle)
Claude Code	Usa los comandos CLI a continuación	-
Codex CLI	Usa los comandos CLI a continuación o ~/.codex/config.toml	-
Gemini CLI	Usa los comandos CLI a continuación o ~/.gemini/settings.json	-
Cursor	Configuración → 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 mediante --max-rows, --max-chars).

Asegurando para producción

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

Para implementaciones de producción con acceso de terceros, recomendamos MotherDuck Remote MCP — sin configuración, compatible con lectura-escritura y alojado por MotherDuck.

Autoalojamiento de 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.

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

Docker

Construye y ejecuta el servidor con Streamable HTTP en el puerto 8000 (por defecto usa 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. Las banderas CLI y las variables de entorno a continuación siguen aplicándose.

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 (predeterminado: true) y que no estés conectado en modo de 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 acción de GitHub 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 de GitHub con el paquete MCPB

Licencia

Licencia MIT - consulta el archivo LICENSE.

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