DuckDB MCP Server

Overview

DuckDB MCP Server enables AI assistants to interact with DuckDB databases through SQL queries. DuckDB is an in-process analytical database system designed for local data analysis, making it perfect for working with CSV files, Parquet files, and other data sources without requiring a separate database server.

Installation

Prerequisites

• Python 3.10 or higher
• pip or uv package manager

Installing via pip

pip install mcp-server-duckdb

Installing via uv

uv pip install mcp-server-duckdb

Configuration

The server requires a path to a DuckDB database file and offers optional parameters for customizing behavior.

Required Parameters

• db-path: Path to the DuckDB database file
  • The server will automatically create the database file and parent directories if they don't exist
  • If using read-only mode and the database doesn't exist, the server will fail to start

Optional Parameters

• --readonly: Run server in read-only mode (default: false)

  • Prevents any write operations to the database
  • If the database file doesn't exist, it won't be created
  • Provides security by ensuring the database remains unaltered

• --keep-connection: Re-use a single DuckDB connection (default: false)

  • Maintains one connection for the entire server lifetime
  • Enables TEMP objects and slightly faster queries
  • May hold an exclusive lock on the database file

Usage Examples

Basic Usage

To start the server with a new or existing database:

mcp-server-duckdb /path/to/your/database.db

Read-Only Mode

To start the server in read-only mode:

mcp-server-duckdb /path/to/your/database.db --readonly

With Connection Reuse

To start the server with a persistent connection:

mcp-server-duckdb /path/to/your/database.db --keep-connection

Working with the Database

Once the server is running, you can use the query tool to interact with the database. Here are some example operations:

1. Create a table:

   CREATE TABLE users (id INTEGER, name VARCHAR, email VARCHAR);
   

2. Insert data:

   INSERT INTO users VALUES (1, 'John Doe', 'john@example.com');
   

3. Query data:

   SELECT * FROM users WHERE id = 1;
   

4. Get schema information:

   PRAGMA table_info(users);
   

5. Load data from CSV:

   CREATE TABLE data AS SELECT * FROM read_csv_auto('/path/to/file.csv');
   

The server will return query results as text, or success messages for operations like CREATE and INSERT.