# mcp-server-motherduck

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 534
- Author: motherduckdb
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/motherduckdb/mcp-server-motherduck
- Updated: 2026-10-07
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-server-motherduck

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `motherduck_token`, `MOTHERDUCK_TOKEN`, `HOME`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`, `AWS_ENDPOINT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
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>

### Codex

**Platform CLI**
```bash
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-motherduck
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-motherduck
```
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>

## When to use it
- 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
- 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

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md