How to add DuckDB MCP Server to Cursor
Query and manage a local DuckDB database from your LLM via the Model Context Protocol. Paste the config into ~/.cursor/mcp.json and restart Cursor.
Last updated June 14, 2026 · 177★ · stdio · no auth
Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
- 2Paste the DuckDB MCP Server config below into the "mcpServers" object.
- 3Fill in placeholder secrets, then save.
- 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
- 5Ask Cursor to use one of DuckDB MCP Server's tools to confirm it's connected.
Before you start
- Python with the uv package manager
- DuckDB Python package
- MCP server dependencies
What DuckDB MCP Server can do in Cursor
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 + Cursor FAQ
Where is the Cursor config file?
Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the DuckDB MCP Server config there under the "mcpServers" key and restart the client.
Is DuckDB MCP Server safe to use with Cursor?
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.