Skip to content

Getting Started

This guide will get you up and running with the DuckDB MCP extension in just a few minutes.

Installation

From the DuckDB Community Extensions repository

The easiest way is to install from the official community registry:

INSTALL duckdb_mcp FROM community;
LOAD duckdb_mcp;

This pulls a prebuilt binary for your DuckDB version and platform. No compilation required.

Building from Source

If you need a development build or an unreleased branch:

# Clone the repository (recursively — submodules are required)
git clone --recursive https://github.com/teaguesterling/duckdb_mcp.git
cd duckdb_mcp

# Build the extension
make

# Run DuckDB with the extension preloaded
./build/release/duckdb

Source builds load the extension from disk:

LOAD 'build/release/extension/duckdb_mcp/duckdb_mcp.duckdb_extension';

Quick Start: Running as an MCP Server

The most common use case is running DuckDB as an MCP server that AI assistants can connect to.

1. Create a Server Init Script

Create a file called init-server.sql:

-- Load the extension (installed via INSTALL FROM community)
LOAD duckdb_mcp;

-- Create some sample data
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name VARCHAR,
    price DECIMAL(10,2),
    category VARCHAR
);

INSERT INTO products VALUES
    (1, 'Widget', 9.99, 'Tools'),
    (2, 'Gadget', 24.99, 'Electronics'),
    (3, 'Gizmo', 14.99, 'Electronics');

-- Start the MCP server (stdio transport for CLI integration)
PRAGMA mcp_server_start('stdio');

2. Run the Server

duckdb -init init-server.sql

The server is now running and listening for MCP requests on stdin/stdout.

3. Connect with Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/mcp.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "my-database": {
      "command": "duckdb",
      "args": ["-init", "/path/to/init-server.sql"]
    }
  }
}

Restart Claude Desktop. Claude can now query your database directly!

Built-in Server Tools

When running as an MCP server, DuckDB exposes these tools to clients:

Tool Description
query Execute read-only SQL queries (formats: json, jsonl, csv, markdown, text)
describe Get table or query schema information
list_tables List all tables and views
database_info Get database overview (schemas, tables, extensions)
export Export query results inline or to a file (file output disabled by default)
execute Run DDL/DML statements (disabled by default)

Example: Query Tool

From an MCP client (like Claude), you can ask:

"What products do we have in the Electronics category?"

Claude will use the query tool:

{
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM products WHERE category = 'Electronics'",
    "format": "markdown"
  }
}

Quick Start: Using as an MCP Client

You can also use DuckDB to connect to external MCP servers.

Connecting to an MCP Server

-- Load the extension
LOAD duckdb_mcp;

-- Attach an MCP server
ATTACH 'python3' AS data_server (
    TYPE mcp,
    TRANSPORT 'stdio',
    ARGS '["path/to/mcp_server.py"]'
);

Reading Data via MCP

-- List available resources
SELECT mcp_list_resources('data_server');

-- Read a specific resource
SELECT mcp_get_resource('data_server', 'file:///data/sales.csv');

-- Use DuckDB's file readers with MCP URIs
SELECT * FROM read_csv('mcp://data_server/file:///data/sales.csv');

Calling Tools

-- List available tools
SELECT mcp_list_tools('data_server');

-- Call a tool
SELECT mcp_call_tool('data_server', 'analyze_sales', '{"year": 2024}');

Output Formats

The query tool supports multiple output formats:

{"name": "query", "arguments": {"sql": "SELECT * FROM products", "format": "json"}}

Returns a JSON array of objects - best for programmatic processing.

{"name": "query", "arguments": {"sql": "SELECT * FROM products", "format": "markdown"}}

Returns a markdown table - recommended for AI assistants as it's more token-efficient.

{"name": "query", "arguments": {"sql": "SELECT * FROM products", "format": "csv"}}

Returns comma-separated values - best for data export.

Next Steps