mcp-server-motherduck — Claude Code MCP server: what it does
Local SQL analytics server powered by DuckDB and MotherDuck. It gives AI coding assistants direct query access to local database files, memory tables, and remote storage.
claude mcp add mcp-server-motherduck -e motherduck_token=<motherduck_token> -e MOTHERDUCK_TOKEN=<MOTHERDUCK_TOKEN> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> -e AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> -e AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> -- uvx mcp-server-motherduckWhat mcp-server-motherduck does
This server connects your development environment directly to DuckDB. The assistant runs SQL queries and inspects database catalogs. You can point it at local .duckdb files or MotherDuck cloud databases. Using read-only mode avoids file locks, so other applications can access the database file simultaneously.
Execution relies on the uv tool. It launches via uvx using flags like --db-path, --read-write, and --allow-switch-databases. Without valid credentials in motherduck_token or AWS environment variables, connections to remote databases will fail immediately.
What it helps with
- Execute analytical SQL queries against local DuckDB files
- Inspect database catalogs and table schemas through conversation
- Ingest local CSV and parquet files into MotherDuck
- Run calculations in temporary memory without persisting files
Example prompts for the agent
- Show the schema and sample rows from the customers table in ./data.duckdb
- Create an in-memory table from records.csv and calculate total revenue
- Query the monthly active users in my MotherDuck analytics database
How to install mcp-server-motherduck
Platform CLI
claude mcp add mcp-server-motherduck -e motherduck_token=<motherduck_token> -e MOTHERDUCK_TOKEN=<MOTHERDUCK_TOKEN> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> -e AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> -e AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> -- uvx mcp-server-motherduckReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-server-motherduck <command>
Platform CLI
codex mcp add mcp-server-motherduck --env motherduck_token=<motherduck_token> --env MOTHERDUCK_TOKEN=<MOTHERDUCK_TOKEN> --env HOME=<HOME> --env AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> --env AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> -- uvx mcp-server-motherduckReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-server-motherduck <command>
Config file
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck"
],
"env": {
"motherduck_token": "<motherduck_token>",
"MOTHERDUCK_TOKEN": "<MOTHERDUCK_TOKEN>",
"HOME": "<HOME>",
"AWS_ACCESS_KEY_ID": "<AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<AWS_SECRET_ACCESS_KEY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-server-motherduck <command>
Config file
{
"servers": {
"mcp-server-motherduck": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-server-motherduck"
],
"env": {
"motherduck_token": "<motherduck_token>",
"MOTHERDUCK_TOKEN": "<MOTHERDUCK_TOKEN>",
"HOME": "<HOME>",
"AWS_ACCESS_KEY_ID": "<AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<AWS_SECRET_ACCESS_KEY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-server-motherduck <command>
Platform CLI
gemini mcp add -e motherduck_token=<motherduck_token> -e MOTHERDUCK_TOKEN=<MOTHERDUCK_TOKEN> -e HOME=<HOME> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> -e AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> mcp-server-motherduck uvx mcp-server-motherduckReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-server-motherduck <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-server-motherduck
How to install mcp-server-motherduck in Claude Code?
Run `claude mcp add mcp-server-motherduck -e motherduck_token=<motherduck_token> -e MOTHERDUCK_TOKEN=<MOTHERDUCK_TOKEN> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> -e AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> -e AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> -- uvx mcp-server-motherduck. Make sure uv` is installed on your system first.
What does mcp-server-motherduck do?
It exposes DuckDB and MotherDuck tools to your AI assistant. This lets the assistant run SQL statements, browse tables, and read or write data locally.
Why use read-only mode for DuckDB files?
Read-only mode prevents DuckDB from holding an exclusive lock on the file. That allows other tools or scripts to read and write to the same database concurrently.
