home / mcp / duckdb mcp server

DuckDB MCP Server

Provides SQL analytics capabilities for local DuckDB databases accessed by AI assistants and IDEs.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "boettiger-lab-mcp-server-duckdb": {
      "command": "uvx",
      "args": [
        "mcp-server-duckdb",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

You run a local DuckDB MCP Server to enable AI assistants and IDEs to query and analyze data from DuckDB databases using SQL. It supports in-memory databases, local DuckDB files, and cloud-backed data, with safe result sizing and convenient integration with MPC clients.

How to use

Connect your MCP client (such as Claude Desktop, Cursor, or VS Code) to a local DuckDB MCP Server. You can point the client to a local in-memory database, a local DuckDB file, or a DuckDB instance stored on S3. Execute SQL queries via the query tool to analyze your data. All results are automatically limited to prevent excessive context use.

How to install

Prerequisites: ensure you have Node.js and a compatible package manager installed. You will also need an MCP client installed if you plan to connect from an external UI.

# Install the MCP server runtime (if not already installed)
# You may use npm, uvx, or another suitable runner as shown in examples

# Example: install uvx globally if needed (adjust to your setup)
npm install -g uvx  # or use your preferred method to obtain uvx

Connect to local DuckDB

To run the MCP server against a local DuckDB setup, choose one of these runtime configurations. Use the path to your local database or switch to in-memory mode for quick experiments.

# In-memory DuckDB
uvx mcp-server-duckdb --db-path :memory:

# Local DuckDB file
uvx mcp-server-duckdb --db-path /path/to/local.db

# Local DuckDB file in read-only mode
uvx mcp-server-duckdb --db-path /path/to/local.db --read-only

Connect to DuckDB on S3

If your DuckDB database is stored on Amazon S3, provide the S3 URL as the database path and supply credentials via environment variables when you start the server.

# Example with S3 URL and environment credentials
uvx mcp-server-duckdb --db-path s3://your-bucket/path/to/database.duckdb

Running in SSE mode

You can expose the server via Server-Sent Events (SSE) in two ways: directly or through a gateway.

# Direct SSE mode
uvx mcp-server-duckdb --transport sse --port 8000 --db-path :memory:

# Through a gateway (example with supergateway)
npx -y supergateway --stdio "uvx mcp-server-duckdb --db-path :memory:"

Troubleshooting

If you encounter local file access issues, verify the home directory configuration, ensure the runtime command (uvx) is in your PATH, and use the full path to the runtime if you see spawn errors.

Tools and limits

The MCP server provides a single tool to run SQL queries against your DuckDB database.

Notes

Query results are automatically limited to 1024 rows by default and 50,000 characters by default to prevent excessive context usage. You can adjust these limits with --max-rows and --max-chars when starting the server.

Available tools

query

Execute a SQL query on the DuckDB database