Choose Your Setup Select the database connection type that matches your use case:
In-Memory Development and testing with a temporary database
Local File Connect to a local DuckDB file (read-only or read-write)
MotherDuck Cloud-based DuckDB with full read-write access
Configuration Examples Add one of these configurations to your MCP client’s configuration file:
Claude Desktop
Claude Code CLI
Cursor
VS Code
Codex CLI
Configuration file location : Settings → Developer → Edit Config In-Memory (Dev Mode)
Local File (Read-Only)
MotherDuck (Read-Write)
{ "mcpServers" : { "DuckDB (in-memory, r/w)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , ":memory:" , "--read-write" , "--allow-switch-databases" ] } } }
Full flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime. { "mcpServers" : { "DuckDB (read-only)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "/absolute/path/to/your.duckdb" ] } } }
Connects to a specific DuckDB file in read-only mode. Won’t hold on to the file lock, so convenient to use alongside a write connection to the same DuckDB file. { "mcpServers" : { "MotherDuck (local, r/w)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "md:" , "--read-write" ], "env" : { "motherduck_token" : "<YOUR_MOTHERDUCK_TOKEN>" } } } }
Connect to MotherDuck with full read-write capabilities. Get your token from the MotherDuck console . Use the claude mcp add command: In-Memory (Dev Mode)
Local File (Read-Only)
MotherDuck (Read-Write)
claude mcp add --scope user duckdb --transport stdio -- \ uvx mcp-server-motherduck \ --db-path :memory: \ --read-write \ --allow-switch-databases
claude mcp add --scope user duckdb --transport stdio -- \ uvx mcp-server-motherduck \ --db-path /absolute/path/to/db.duckdb
claude mcp add --scope user motherduck --transport stdio \ --env motherduck_token=YOUR_TOKEN -- \ uvx mcp-server-motherduck \ --db-path md: \ --read-write
Configuration location : Settings → MCP → Add new global MCP server In-Memory (Dev Mode)
Local File (Read-Only)
MotherDuck (Read-Write)
{ "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , ":memory:" , "--read-write" , "--allow-switch-databases" ] }
Or use the one-click install: { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "/absolute/path/to/your.duckdb" ] }
{ "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "md:" , "--read-write" ], "env" : { "motherduck_token" : "<YOUR_MOTHERDUCK_TOKEN>" } }
Configuration location : Ctrl+Shift+P → “Preferences: Open User Settings (JSON)”Add to your settings.json: In-Memory (Dev Mode)
Local File (Read-Only)
MotherDuck (Read-Write)
{ "mcp.servers" : { "DuckDB (in-memory, r/w)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , ":memory:" , "--read-write" , "--allow-switch-databases" ] } } }
{ "mcp.servers" : { "DuckDB (read-only)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "/absolute/path/to/your.duckdb" ] } } }
{ "mcp.servers" : { "MotherDuck (local, r/w)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "md:" , "--read-write" ], "env" : { "motherduck_token" : "<YOUR_MOTHERDUCK_TOKEN>" } } } }
Use the codex mcp add command: In-Memory (Dev Mode)
Local File (Read-Only)
MotherDuck (Read-Write)
codex mcp add duckdb -- \ uvx mcp-server-motherduck \ --db-path :memory: \ --read-write \ --allow-switch-databases
codex mcp add duckdb -- \ uvx mcp-server-motherduck \ --db-path /absolute/path/to/db.duckdb
codex mcp add motherduck \ --env motherduck_token=YOUR_TOKEN -- \ uvx mcp-server-motherduck \ --db-path md: \ --read-write
Important : Replace /absolute/path/to/your.duckdb with the actual absolute path to your DuckDB file, and <YOUR_MOTHERDUCK_TOKEN> with your MotherDuck access token.
Run Your First Query After configuring your MCP client, restart the application and try executing a SQL query:
-- Create a sample table CREATE TABLE users AS SELECT * FROM ( VALUES ( 1 , 'Alice' , '[email protected] ' ), ( 2 , 'Bob' , '[email protected] ' ), ( 3 , 'Charlie' , '[email protected] ' ) ) AS t(id, name , email); -- Query the data SELECT * FROM users WHERE name LIKE 'A%' ;
You can ask your AI assistant to:
“Execute a SQL query to show all users”
“List all tables in the database”
“Describe the schema of the users table”
“Create a summary of data by grouping”
Use the execute_query tool to run any DuckDB SQL query. The server supports the full DuckDB SQL dialect including CTEs, window functions, and analytical operations.
S3 Database Connections You can also connect to DuckDB files hosted on S3:
{ "mcpServers" : { "DuckDB (S3)" : { "command" : "uvx" , "args" : [ "mcp-server-motherduck" , "--db-path" , "s3://bucket/path/to/database.duckdb" ], "env" : { "AWS_ACCESS_KEY_ID" : "<YOUR_AWS_KEY>" , "AWS_SECRET_ACCESS_KEY" : "<YOUR_AWS_SECRET>" , "AWS_DEFAULT_REGION" : "us-east-1" } } } }
Next Steps
Configuration Options Explore advanced configuration options for security, performance tuning, and more
Available Tools Learn about all available MCP tools including execute_query, list_tables, and more
Security Guide Secure your MCP server for production deployments with third-party access
Troubleshooting Common issues and solutions for MCP Server MotherDuck
Migration Notes If you’re migrating from v0.x, be aware of these important changes:
Read-only by default : The server now runs in read-only mode by default. Add --read-write to enable write access.Default database changed : --db-path default changed from md: to :memory:. Add --db-path md: explicitly for MotherDuck.MotherDuck read-only requires read-scaling token : MotherDuck connections in read-only mode require a read-scaling token . Regular tokens require --read-write. 