Metadata-Version: 2.4
Name: iflow-mcp_duckdb-mcp-server
Version: 0.1.0
Summary: A MCP server for DuckDB that enables LLMs to query and analyze data from various sources
Project-URL: Homepage, https://github.com/yourusername/duckdb-mcp-server
Project-URL: Bug Tracker, https://github.com/yourusername/duckdb-mcp-server/issues
License: MIT License
        
        Copyright (c) 2024
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: boto3>=1.26.0
Requires-Dist: duckdb>=1.2.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# DuckDB MCP Server

[![PyPI - Version](https://img.shields.io/pypi/v/duckdb-mcp-server)](https://pypi.org/project/duckdb-mcp-server/)
[![PyPI - License](https://img.shields.io/pypi/l/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.
