mcp-server-duckdb
Author: ktanaka101
Description: Model Context Protocol server that exposes a single SQL ‘query’ tool backed by a DuckDB database. Supports read-only mode, reusable connections and easy Claude Desktop / Smithery integration.
Stars: 141
Forks: 14
License: MIT License
Category: Open Source
Overview
Installation
1. Install Python ≥ 3.8.
2. Create a virtual environment (recommended):
python -m venv venv && source venv/bin/activate3. Install the server package and DuckDB:
pip install mcp-server-duckdb duckdb4. (Optional) Pin a specific DuckDB version:
pip install "duckdb==0.10.*"5. Export configuration – the server looks for these environment variables:
• DUCKDB_FILE – path to the DuckDB database file (default: ./database.duckdb)
• MCP_SERVER_HOST – listening interface (default: 0.0.0.0)
• MCP_SERVER_PORT – TCP port (default: 8000)
6. Launch the service:
mcp-server-duckdb # wrapper script installed by the package
# or, if based on FastAPI, run directly with Uvicorn
uvicorn mcp_server_duckdb.app:app --host ${MCP_SERVER_HOST:-0.0.0.0} --port ${MCP_SERVER_PORT:-8000}7. Verify the health-check endpoint:
curl http://localhost:8000/health01
query
Execute any SQL query on the DuckDB database
License: MIT License
Updated 7/30/2025