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

Install Claude Desktop from claude.ai/download
Edit Claude Desktop's configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
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:

Explicit credentials (if --creds-from-env is enabled)
Named profile credentials (via --s3-profile)
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.

DuckDB Data Analysis