Information
# DuckDB MCP Server
[](https://pypi.org/project/duckdb-mcp-server/)
[](LICENSE)
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](https://duckdb.org/) - a high-performance analytical database - through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). 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
\`\`\`bash
pip install duckdb-mcp-server
\`\`\`
### From source
\`\`\`bash
git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .
\`\`\`
## Configuration
### Command Line Options
\`\`\`bash
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](https://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:
\`\`\`json
\{
"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:
\`\`\`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:
\`\`\`sql
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
\`\`\`bash
# 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](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.