How to add DuckDB MCP Server to Windsurf
Query and manage a local DuckDB database from your LLM via the Model Context Protocol. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 177★ · stdio · no auth
Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the DuckDB MCP Server config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5DuckDB MCP Server's tools become available to Cascade.
Before you start
- Python with the uv package manager
- DuckDB Python package
- MCP server dependencies
What DuckDB MCP Server can do in Windsurf
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 + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_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 Windsurf?
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.