duckdb-mcp-server

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 file for details.

🙏 Contributing

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