DuckDB MCP Server
Query and manage a local DuckDB database from your LLM via the Model Context Protocol.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @smithery/cli install mcp-server-duckdb --client claudePaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"duckdb-mcp-server": {
"command": "uvx",
"args": [
"mcp-server-duckdb",
"--db-path",
"~/mcp-server-duckdb/data/data.db"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python with the uv package manager
- DuckDB Python package
- MCP server dependencies
About DuckDB MCP Server
This server enables interaction with a DuckDB database through the Model Context Protocol, allowing for database operations like querying, table creation, and schema inspection. It is published as the PyPI package mcp-server-duckdb and is typically launched via uvx. The required --db-path parameter points to the DuckDB database file; the server automatically creates the file and parent directories if they don't exist (unless running in read-only mode). DuckDB's local, in-process analytical engine makes this a good fit for letting an LLM analyze local datasets.
Tools & capabilities (1)
queryExecute any valid DuckDB SQL statement on the database. Input: query (string). Output: query results as text, or a success message for operations like CREATE/INSERT. A single unified tool handles SELECT, CREATE TABLE, JOIN, and other operations.
When to use it
- Let an LLM run ad-hoc SQL analysis over a local DuckDB database
- Create tables and load/insert data conversationally
- Inspect database schemas and explore datasets
- Expose a read-only DuckDB database safely to an LLM for analysis without risk of writes
Security notes
When running in --readonly mode, DuckDB's native readonly protection is enforced, preventing the LLM from performing any write operations (CREATE, INSERT, UPDATE, DELETE) and maintaining data integrity. If --readonly is specified and the database file does not exist, the server will not create it and will fail to start. Without --readonly, the server can execute arbitrary SQL (including writes) against the specified database file.
DuckDB MCP Server FAQ
How do I prevent the LLM from modifying my data?
Start the server with the --readonly flag. DuckDB opens the connection with read_only=True, blocking all write operations (CREATE, INSERT, UPDATE, DELETE). Note that in read-only mode the database file must already exist, or the server will fail to start.
Why is there only one query tool instead of separate tools for each operation?
The server intentionally provides a single unified query function. Modern LLMs can generate appropriate SQL for any database operation (SELECT, CREATE TABLE, JOIN, etc.) without requiring separate endpoints.
What does --keep-connection do?
It re-uses a single DuckDB connection for the entire server lifetime, enabling TEMP objects and slightly faster queries, but it can hold an exclusive lock on the database file. It defaults to false.
How do I install it for Claude Desktop?
Either install automatically via Smithery (npx -y @smithery/cli install mcp-server-duckdb --client claude), or manually add the mcpServers config block to claude_desktop_config.json using the uvx command with the mcp-server-duckdb package and a --db-path argument.
Alternatives to DuckDB MCP Server
Compare all alternatives →
Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.
Read/write Postgres access plus index tuning, EXPLAIN plans, and database health analysis for AI agents.
Official Supabase server: manage tables, run SQL, branches, configs and edge functions from your AI client.
Compare DuckDB MCP Server with: