What is Duckdb Mcp Server

DuckDB MCP Server is an implementation of the Model Context Protocol (MCP) that allows AI assistants like Claude to interact with DuckDB, a high-performance analytical database, enabling powerful data analysis capabilities on remote files.

Use cases

Use cases include querying data from different file formats, performing complex SQL analyses, and generating insights from data stored in cloud services like S3.

How to use

To use DuckDB MCP Server, install it via pip with ‘pip install duckdb-mcp-server’, or clone the repository and install from source. Configure it by specifying the database path using command line options.

Key features

Key features include a powerful SQL query tool, support for multiple data sources (local files, cloud storage, SQLite databases), automatic connection management, smart credential handling for AWS/S3, and built-in documentation resources.

Where to use

DuckDB MCP Server can be used in various fields such as data analysis, machine learning, and AI development, particularly where integration with DuckDB’s analytical capabilities is beneficial.

DuckDB MCP Server

A Model Context Protocol (MCP) server implementation that enables AI assistants like Claude to interact with DuckDB for powerful data analysis capabilities.

🌟 What is DuckDB MCP Server?

DuckDB MCP Server connects AI assistants to DuckDB - a high-performance analytical database - through the Model Context Protocol (MCP). This allows AI models to:

• Query data directly from various sources like CSV, Parquet, JSON, etc.
• Access data from cloud storage (S3, etc.) without complex setup
• Perform sophisticated data analysis using SQL
• Generate data insights with proper context and understanding

🚀 Key Features

• SQL Query Tool: Execute any SQL query with DuckDB’s powerful syntax
• Multiple Data Sources: Query directly from:
  • Local files (CSV, Parquet, JSON, etc.)
  • S3 buckets and cloud storage
  • SQLite databases
  • All other data sources supported by DuckDB
• Auto-Connection Management: Automatic database file creation and connection handling
• Smart Credential Handling: Seamless AWS/S3 credential management
• Documentation Resources: Built-in DuckDB SQL and data import reference for AI assistants

📋 Requirements

• Python 3.10+
• An MCP-compatible client (Claude Desktop, Cursor, VS Code with Copilot, etc.)

💻 Installation

Using pip

pip install duckdb-mcp-server

From source

git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .

🔧 Configuration

Command Line Options

duckdb-mcp-server --db-path path/to/database.db [options]

Required Parameters:

• --db-path - Path to DuckDB database file (will be created if doesn’t exist)

Optional Parameters:

• --readonly - Run in read-only mode (will error if database doesn’t exist)
• --s3-region - AWS S3 region (default: uses AWS_DEFAULT_REGION env var)
• --s3-profile - AWS profile for S3 credentials (default: uses AWS_PROFILE or ‘default’)
• --creds-from-env - Use AWS credentials from environment variables

🔌 Setting Up with Claude Desktop

1. Install Claude Desktop from claude.ai/download

2. Edit Claude Desktop’s configuration file:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   Windows: %APPDATA%/Claude/claude_desktop_config.json

3. Add DuckDB MCP Server configuration:

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

📊 Example Usage

Once configured, you can ask your AI assistant to analyze data using DuckDB:

"Load the sales.csv file and show me the top 5 products by revenue"

The AI will generate and execute the appropriate SQL:

-- Load and query the CSV data
SELECT 
    product_name,
    SUM(quantity * price) AS revenue
FROM read_csv('sales.csv')
GROUP BY product_name
ORDER BY revenue DESC
LIMIT 5;

Working with S3 Data

Query data directly from S3 buckets:

"Analyze the daily user signups from our analytics data in S3"

The AI will generate appropriate SQL to query S3:

SELECT 
    date_trunc('day', signup_timestamp) AS day,
    COUNT(*) AS num_signups
FROM read_parquet('s3://my-analytics-bucket/signups/*.parquet')
GROUP BY day
ORDER BY day DESC;

🌩️ Cloud Storage Authentication

DuckDB MCP Server handles AWS authentication in this order:

1. Explicit credentials (if --creds-from-env is enabled)
2. Named profile credentials (via --s3-profile)
3. Default credential chain (environment, shared credentials file, etc.)

🛠️ Development

# Clone the repository
git clone https://github.com/yourusername/duckdb-mcp-server.git
cd duckdb-mcp-server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.