home / mcp / duckdb mcp server

DuckDB MCP Server

A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities

Installation

Add the following to your MCP client configuration file.

Configuration

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

This MCP server lets you interact with a DuckDB database through the Model Context Protocol, enabling you to run SQL queries, inspect schemas, and manage tables from an MCP client. It’s designed for local analysis and safe experimentation by exposing a single unified query endpoint and optional read-only protections to prevent unintended writes.

How to use

Connect to the DuckDB MCP server from your MCP client and issue SQL through the query endpoint. You can perform SELECT queries to retrieve data, CREATE and ALTER statements to shape your schema, and DDL/DML operations as needed. When you submit a statement, you’ll receive either the textual results of the query or a confirmation message for operations such as CREATE or INSERT. If you enable read-only mode, write operations are blocked automatically by DuckDB’s protections, ensuring the database remains unchanged.

How to install

Prerequisites: you should have Python installed and access to the MCP runtime tooling (uvx). You also need DuckDB Python bindings if you plan to run locally and test with Python tooling.

Install the DuckDB MCP server using Smithery to enable client integrations like Claude Desktop. Run the following command in your terminal:

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

Claude Desktop integration configuration

In Claude Desktop, configure the MCP server with a local stdio connection that runs the server using the provided runtime. Use the following example configuration for macOS or Windows respectively.

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

Security and runtime options

Configuration supports a read-only mode to prevent any write operations. When enabled, DuckDB opens with read-only protections and will not create the database file if it does not exist. This provides a security boundary to ensure the LLM cannot modify data.

You can also choose to reuse a single DuckDB connection for the server lifetime by enabling the --keep-connection option. This improves performance for repeated queries but may hold an exclusive lock on the database file.

Configuration details

Required parameter: db-path — path to the DuckDB database file. The server will automatically create the database file and its parent directories if they do not exist. If you start the server with --readonly and the database file does not exist, startup will fail.

Optional parameters: --readonly to run in read-only mode (default: false) and --keep-connection to reuse a single connection (default: false). When read-only, the LLM cannot perform CREATE, INSERT, UPDATE, or DELETE operations.

Troubleshooting and debugging

If you need to debug MCP server interactions, use an MCP Inspector tool to observe request/response flows, tool execution, server state, and error messages. You can start the inspector with a command that targets your MCP server and database path to view live interactions.

Available tools

query

Execute any DuckDB SQL statement against the configured database and return results as text or a success message for non-query operations like CREATE or INSERT.