Quick Start
Prerequisites: Install uv via pip install uv or brew install uv
Connecting to In-Memory DuckDB (Dev Mode)
{
"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.
Connecting to a Local DuckDB File in Read-Only Mode
{
"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. You can also connect to remote DuckDB files on S3 using s3://bucket/path.duckdb — see Environment Variables for S3 authentication. If you're considering third-party access to the MCP, see Securing for Production.
Connecting to MotherDuck in Read-Write Mode
{
"mcpServers": {
"MotherDuck (local, r/w)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
"env": {
"motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
}
}
}
}
See Command Line Parameters for more options, Securing for Production for deployment guidance, and Troubleshooting if you encounter issues.
Client Setup
| Client | Config Location | One-Click Install |
|---|
| Claude Desktop | Settings → Developer → Edit Config | .mcpb (MCP Bundle) |
| Claude Code | Use CLI commands below | - |
| Codex CLI | Use CLI commands below or ~/.codex/config.toml | - |
| Gemini CLI | Use CLI commands below or ~/.gemini/settings.json | - |
| Cursor | Settings → MCP → Add new global MCP server | |
| VS Code | Ctrl+Shift+P → "Preferences: Open User Settings (JSON)" | |
| Kiro | ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json (project) | |
Any MCP-compatible client can use this server. Add the JSON configuration from Quick Start to your client's MCP config file. Consult your client's documentation for the config file location.
In-Memory DuckDB (Dev Mode):
claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
Local DuckDB (Read-Only):
claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
MotherDuck (Read-Write):
claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write
In-Memory DuckDB (Dev Mode):
codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
Local DuckDB (Read-Only):
codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
MotherDuck (Read-Write):
codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write
In-Memory DuckDB (Dev Mode):
gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
Local DuckDB (Read-Only):
gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
MotherDuck (Read-Write):
gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write
Add the following to your Kiro MCP config file (~/.kiro/settings/mcp.json for global, or .kiro/settings/mcp.json for project-scoped). See the Kiro MCP documentation for more details.
In-Memory DuckDB (Dev Mode):
{
"mcpServers": {
"DuckDB (in-memory, r/w)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
}
}
}
MotherDuck (Read-Write):
{
"mcpServers": {
"MotherDuck (local, r/w)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
"env": {
"motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
}
}
}
}