servidor mcp-duckdb

Implementación de un servidor de Protocolo de Contexto de Modelo (MCP) para DuckDB, que proporciona capacidades de interacción con bases de datos mediante herramientas MCP. Sería interesante que LLM lo analizara. DuckDB es adecuado para el análisis local.

Descripción general

Este servidor permite la interacción con una base de datos DuckDB a través del Protocolo de Contexto de Modelo, lo que permite operaciones de base de datos como consultas, creación de tablas e inspección de esquemas.

Related MCP server: MotherDuck DuckDB MCP Server

Componentes

Recursos

Actualmente, no hay recursos personalizados implementados.

Indicaciones

Actualmente, no se implementan indicaciones personalizadas.

Herramientas

El servidor implementa la siguiente herramienta de interacción con la base de datos:

• consulta : ejecuta cualquier consulta SQL en la base de datos DuckDB

  • Entrada : query (cadena): cualquier declaración SQL de DuckDB válida

  • Salida : Resultados de la consulta como texto (o mensaje de éxito para operaciones como CREAR/INSERTAR)

[!NOTA] El servidor proporciona una única función query unificada en lugar de funciones especializadas separadas, ya que los LLM modernos pueden generar SQL apropiado para cualquier operación de base de datos (SELECT, CREATE TABLE, JOIN, etc.) sin requerir puntos finales separados.

[!NOTA] Cuando el servidor se ejecuta en modo readonly , se aplica la protección de solo lectura nativa de DuckDB. Esto garantiza que el Modelo de Lenguaje (LLM) no pueda realizar operaciones de escritura (CREAR, INSERTAR, ACTUALIZAR, ELIMINAR), manteniendo la integridad de los datos y evitando cambios no deseados.

Configuración

Parámetros requeridos

• db-path (cadena): Ruta al archivo de base de datos DuckDB

  • El servidor creará automáticamente el archivo de base de datos y los directorios principales si no existen

  • Si se especifica --readonly y el archivo de base de datos no existe, el servidor no podrá iniciarse y mostrará un error.

Parámetros opcionales

• --readonly : Ejecutar el servidor en modo de solo lectura

  • Descripción : Cuando esta bandera está activada, el servidor opera en modo de solo lectura. Esto significa:

    • La base de datos DuckDB se abrirá con read_only=True , evitando cualquier operación de escritura.

    • Si el archivo de base de datos especificado no existe, no se creará.

    • Beneficio de seguridad : evita que el modelo de lenguaje (LLM) realice operaciones de escritura, lo que garantiza que la base de datos permanezca inalterada.

  • Referencia : para obtener más detalles sobre las conexiones de solo lectura en DuckDB, consulte la documentación de la API de Python de DuckDB .

Instalación

Instalación mediante herrería

Para instalar DuckDB Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install mcp-server-duckdb --client claude

Integración de escritorio de Claude

Configure el servidor MCP en el archivo de configuración de Claude Desktop:

Sistema operativo Mac

Ubicación: ~/Library/Application Support/Claude/claude_desktop_config.json

Ventanas

Ubicación: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "duckdb": {
      "command": "uvx",
      "args": [
        "mcp-server-duckdb",
        "--db-path",
        "~/mcp-server-duckdb/data/data.db"
      ]
    }
  }
}

• Nota: ~/mcp-server-duckdb/data/data.db debe reemplazarse con la ruta real al archivo de base de datos DuckDB.

Desarrollo

Prerrequisitos

• Python con el gestor de paquetes uv

• Paquete Python de DuckDB

• Dependencias del servidor MCP

Depuración

Depurar servidores MCP puede ser complicado debido a su comunicación basada en stdio. Recomendamos usar el Inspector MCP para una mejor experiencia de depuración.

Uso del inspector MCP

1. Instalar el inspector usando npm:

npx @modelcontextprotocol/inspector uv --directory ~/codes/mcp-server-duckdb run mcp-server-duckdb --db-path ~/mcp-server-duckdb/data/data.db

2. Abra la URL proporcionada en su navegador para acceder a la interfaz de depuración

El inspector proporciona visibilidad sobre:

• Comunicación de solicitud/respuesta

• Ejecución de herramientas

• Estado del servidor

• Mensajes de error