How to add DuckDB MCP Server to Claude Desktop
Query and manage a local DuckDB database from your LLM via the Model Context Protocol. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.
Last updated June 14, 2026 · 177★ · stdio · no auth
Claude Desktop config for DuckDB MCP Server
npx -y @smithery/cli install mcp-server-duckdb --client claude{
"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.
Setup steps
- 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
- 2Paste the DuckDB MCP Server config below under the top-level "mcpServers" key.
- 3Fill in any placeholder secrets (API keys, paths) in the snippet.
- 4Save the file, then fully quit and reopen Claude Desktop.
- 5Open a chat and confirm DuckDB MCP Server's tools appear under the 🔌 tools menu.
Before you start
- Python with the uv package manager
- DuckDB Python package
- MCP server dependencies
What DuckDB MCP Server can do in Claude Desktop
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.
Security
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 + Claude Desktop FAQ
Where is the Claude Desktop config file?
Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the DuckDB MCP Server config there under the "mcpServers" key and restart the client.
Is DuckDB MCP Server safe to use with Claude Desktop?
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.
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.