📌Overview

Purpose: To provide a server implementation for interacting with DuckDB through the Model Context Protocol (MCP), facilitating database operations.

Overview: This server allows users to execute various database operations, including querying, table creation, and schema inspection, utilizing DuckDB's capabilities via the MCP framework.

Key Features:

• Unified Query Tool: Offers a single query function to execute any valid DuckDB SQL statement, streamlining interaction without the need for multiple endpoints.

• Read-only Mode: Ensures data integrity by allowing the server to operate in read-only mode, preventing any write operations and protecting the database from changes.

---

mcp-server-duckdb

A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools. DuckDB is suitable for local analysis.

Overview

This server enables interaction with a DuckDB database through the Model Context Protocol, allowing for operations such as querying, table creation, and schema inspection.

Components

Tools

The server implements a single database interaction tool:

• query: Execute any SQL query on the DuckDB database
  • Input: query (string) - Any valid DuckDB SQL statement
  • Output: Query results as text or success message for operations like CREATE/INSERT

Note: The server provides a unified query function, allowing modern LLMs to generate appropriate SQL for any operation without separate endpoints.

Note: In readonly mode, DuckDB's native readonly protection enforces that no write operations can be performed, maintaining data integrity.

Configuration

Required Parameters

• db-path (string): Path to the DuckDB database file. The server will create the database file and directories if they don't exist.

Optional Parameters

• --readonly: Run the server in read-only mode. This prevents any write operations and ensures the database remains unaltered.

Installation

Installing via Smithery

To install DuckDB Server via Smithery:

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

Claude Desktop Integration

Configure the MCP server in Claude Desktop's configuration file:

MacOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

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

• Note: Replace ~/mcp-server-duckdb/data/data.db with the actual path to the DuckDB database file.

Development

Prerequisites

• Python with uv package manager
• DuckDB Python package
• MCP server dependencies

Debugging

We recommend using the MCP Inspector for debugging MCP servers.

Using MCP Inspector

1. Install the inspector using npm:

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

2. Open the provided URL in your browser to access the debugging interface.

The inspector provides visibility into:

• Request/response communication
• Tool execution
• Server state
• Error messages