LABSCO SUMMARY

Schema comments reach the model, so the first query is written against documented columns rather than guessed ones.

Listing tables and columns returns the comments alongside the names and types, which is the difference between a model inventing what status means and reading it. The safety posture is set once at startup — read-only by default, writes and database switching each their own flag — and holds for every database the session reaches afterwards.

What it is

A SQL front end to DuckDB and MotherDuck: execute queries, describe what is in the database, and move the connection between databases mid-session. It reads local files, in-memory databases, DuckDB files on S3, and MotherDuck, and it starts read-only unless you say otherwise.

What you get

SQL execution where unqualified table names resolve against the current database and schema, so fully qualified names are only needed once several databases are attached
The databases available on the connection, which is what tells you whether you are looking at one attached file, several, or MotherDuck
Tables and views listed with the comments stored against them, and columns listed with their types and comments — the documentation a model needs before it writes a query
A connection switch to another database at runtime, by absolute path for a local file, available only when the server was started with that switch enabled
Read-only by default, with --read-write as the deliberate opt-in, and a SaaS mode that shuts off local filesystem access entirely
Results bounded so a wide query cannot flood the context: 1024 rows and 50000 characters by default, both adjustable, with an optional query timeout
A SQL file or statement run at startup, for attaching databases or setting up extensions before the first question

Requirements

uv, and a database to point at — --db-path takes :memory:, a file path, an s3:// path or md: for MotherDuck, and defaults to an in-memory database. MotherDuck needs a token in motherduck_token, and in read-only mode it specifically needs a read-scaling token; an ordinary token requires --read-write. S3 paths use the usual AWS environment variables. Switching databases mid-session only works if the server was started with --allow-switch-databases, and the read-only or read-write mode it started in follows the connection wherever you switch it. MotherDuck also runs a fully hosted remote server if you would rather not install anything. MIT licensed.

Setup effort

One command — uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

See installation options

USE CASES

01

Answering an analytics question against a local file

List the tables, read the columns and their comments, then run the SQL — all read-only, with no risk to the file.

list_tableslist_columnsexecute_query

02

Working across a local file and a cloud warehouse

See which databases the connection has, then switch to the one the next question is about.

list_databasesswitch_database_connection

03

Exploring a dataset you have just been handed

Start in-memory, read the file straight from S3 or disk with SQL, and keep the result sets bounded while you look around.

execute_querylist_tables

04

Building a table from what you found

With write access enabled, create and populate the table in the same session rather than exporting a query and reloading it.

execute_querylist_columns

5 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`execute_query`

Execute a SQL query on the DuckDB or MotherDuck database. Unqualified table names resolve to current_database() and current_schema() automatically. Fully qualified names (database.schema.table) are only needed when multiple DuckDB databases are attached or when connected to MotherDuck.

BEFORE YOU INSTALL

What to know first

Tools you get

5 tools when we connected. switch_database_connection requires --allow-switch-databases, so a default launch exposes 4. The server is read-only by default; execute_query won't write until you pass --read-write.

Requires

uvx on PATH

CONTEXT COST

Light Standing cost

Rated by the size of the 5 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

TERMINAL

uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

MCP Clients

Claude Desktop, Cursor

JSON

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:",
        "--read-write",
        "--allow-switch-databases"
      ]
    }
  }
}

Claude Code

CLAUDE CODE · TERMINAL

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

Claude Code — MotherDuck token

CLAUDE CODE — MOTHERDUCK TOKEN · TERMINAL

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=<YOUR_MOTHERDUCK_TOKEN> -- uvx mcp-server-motherduck --db-path md: --read-write

Codex

CODEX · TERMINAL

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

Gemini CLI

GEMINI CLI · TERMINAL

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

VS Code

VS CODE · JSON

{
  "servers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:",
        "--read-write",
        "--allow-switch-databases"
      ]
    }
  }
}

Kiro

KIRO · JSON

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--read-write"
      ],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Any MCP client — Docker HTTP

ANY MCP CLIENT — DOCKER HTTP · TERMINAL

git clone https://github.com/motherduckdb/mcp-server-motherduck
cd mcp-server-motherduck
docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

The MCP endpoint is available at http://localhost:8000/mcp.

Any MCP client — local build

ANY MCP CLIENT — LOCAL BUILD · TERMINAL

git clone https://github.com/motherduckdb/mcp-server-motherduck

Point --directory at that clone.

ANY MCP CLIENT — LOCAL BUILD · JSON

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH_TO_MCP_SERVER_MOTHERDUCK>",
        "run",
        "mcp-server-motherduck",
        "--db-path",
        "md:"
      ],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

MotherDuck

Schema comments reach the model, so the first query is written against documented columns rather than guessed ones.

What it is

What you get

Requirements

Setup effort

Answering an analytics question against a local file

Working across a local file and a cloud warehouse

Exploring a dataset you have just been handed

Building a table from what you found

5 tools

`execute_query`

`list_columns`

`list_databases`

`list_tables`

`switch_database_connection`

What to know first

Tools you get

Requires

Light Standing cost

Connect your client

Server setup

MCP Clients

Claude Desktop, Cursor

Claude Code

Claude Code — MotherDuck token

Codex

Gemini CLI

VS Code

Kiro

Any MCP client — Docker HTTP

Any MCP client — local build

MotherDuck

Schema comments reach the model, so the first query is written against documented columns rather than guessed ones.

What it is

What you get

Requirements

Setup effort

Answering an analytics question against a local file

Working across a local file and a cloud warehouse

Exploring a dataset you have just been handed

Building a table from what you found

5 tools

execute_query

list_columns

list_databases

list_tables

switch_database_connection

What to know first

Tools you get

Requires

Light Standing cost

Connect your client

Server setup

MCP Clients

Claude Desktop, Cursor

Claude Code

Claude Code — MotherDuck token

Codex

Gemini CLI

VS Code

Kiro

Any MCP client — Docker HTTP

Any MCP client — local build

Same category

MSSQL Query & Insights Server

Hologres

MCP Data Pipeline Connector

MCP Alchemy

`execute_query`

`list_columns`

`list_databases`

`list_tables`

`switch_database_connection`