agents-libagents-lib
AgentsMCP ServersWorkflowsTutorialsComparisonsTemplatesNewsAbout
🔌

DuckDB MCP

Database•⭐ 520

Query and analyze data using DuckDB in-memory analytical database.

GitHubWebsite →
Claude DesktopCursor

Overview

Query and analyze data using DuckDB in-memory analytical database.

Setup

Run with npx:

npx -y @modelcontextprotocol/server-duckdb

Configuration

Database path as argument

Documentation

DuckDB MCP

Overview

DuckDB MCP is a Model Context Protocol server that provides integration with DuckDB, an in-memory analytical database optimized for OLAP (Online Analytical Processing) workloads. It enables AI agents to query and analyze data using SQL directly within their workflow.

DuckDB is designed for fast analytical queries on large datasets, supporting complex aggregations, joins, and window functions with excellent performance.

Features

  • SQL Query Execution — Run SQL queries against DuckDB databases
  • Multiple File Formats — Support for CSV, Parquet, JSON, and more
  • In-Memory Processing — Fast queries without disk I/O
  • Columnar Storage — Optimized for analytical workloads
  • Vector Extensions — Support for vector operations
  • Streaming Queries — Process large datasets in streams

Installation

npx -y @modelcontextprotocol/server-duckdb

Configuration

{
  "mcpServers": {
    "duckdb": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-duckdb", "/path/to/database.db"],
      "env": {
        "DUCKDB_EXTENSIONS": "httpfs, parquet"
      }
    }
  }
}

Available Tools

ToolDescription
queryExecute a SQL query
list_tablesList tables in the database
describe_tableGet schema of a table
export_queryExport query results to file
attach_databaseAttach an external database

Usage Examples

Query Data

result = duckdb.query("""
    SELECT 
        category,
        COUNT(*) as count,
        AVG(price) as avg_price
    FROM products
    GROUP BY category
    ORDER BY count DESC
""")
print(result.df())

Analyze CSV File

# Read CSV directly
result = duckdb.query("""
    SELECT 
        strftime(date, '%Y-%m') as month,
        SUM(amount) as total
    FROM read_csv_auto('sales.csv')
    GROUP BY month
    ORDER BY month
""")

Query Parquet File

result = duckdb.query("""
    SELECT 
        user_id,
        COUNT(*) as event_count
    FROM 'events/*.parquet'
    GROUP BY user_id
    ORDER BY event_count DESC
    LIMIT 10
""")

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "duckdb": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-duckdb", "/path/to/data.db"]
    }
  }
}

Pros

  • ✅ Fast analytical queries
  • ✅ No server required (embedded database)
  • ✅ Support for multiple file formats
  • ✅ SQL-compliant
  • ✅ Excellent for data analysis
  • ✅ Lightweight and portable

Cons

  • ❌ Not designed for OLTP workloads
  • ❌ Single-threaded by default
  • ❌ Limited concurrent connection support
  • ❌ Not suitable for web applications

When to Use

DuckDB MCP is ideal for:

  • Data analysis and exploration
  • Running analytical queries on CSV/Parquet files
  • Aggregating and summarizing data
  • Prototyping data pipelines
  • Local data processing

Consider alternatives when:

  • You need concurrent web access (use PostgreSQL)
  • You need real-time transactions (use SQLite)
  • You need distributed processing (use Spark)

Resources