# mcp-server-motherduck [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/motherduckdb/mcp-server-motherduck  
**GitHub Stars:** 534  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-motherduck

## Description
Fast analytics and data processing with DuckDB and MotherDuck

## Tools
Capabilities this server exposes over MCP:

- **execute_query** — Execute SQL query (DuckDB dialect)
- **list_databases** — List all databases (useful for MotherDuck or multiple attached DBs)
- **list_tables** — List tables and views
- **list_columns** — List columns of a table/view

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-server-motherduck": {
    "command": "uvx",
    "args": ["mcp-server-motherduck"]
  }
}
```

## Documentation

## What mcp-server-motherduck does

The mcp-server-motherduck MCP server gives an MCP-compatible AI client access to DuckDB's analytical SQL engine. It can work with an in-memory database, a local DuckDB file, a DuckDB database on S3, or MotherDuck. The process runs locally rather than using MotherDuck's hosted remote MCP service.

The server supports SQL reads and writes, but new installations start in read-only mode. Write operations require the `--read-write` option. This makes it suitable for inspecting data by default, while allowing explicitly configured development or trusted environments to mutate databases.

## How it works

The mcp-server-motherduck MCP server is launched as a local MCP process, commonly through `uvx`. The database target is selected with `--db-path`; examples include `:memory:`, an absolute `.duckdb` path, an `s3://` URL, and `md:` for MotherDuck. A MotherDuck connection uses a token supplied through the client environment configuration.

Clients call `execute_query` with SQL written in DuckDB dialect. Catalog tools expose available databases, tables, views, and columns so an agent can inspect a data source before querying it. `list_tables` and `list_columns` accept database and schema selectors where applicable.

The optional `switch_database_connection` tool permits changing the active database connection at runtime. It is only available when the server starts with `--allow-switch-databases`; this option can also permit creating a missing database when requested. Tool responses are returned as JSON.

## Setup and configuration

Install `uv` before using the quick-start configurations. A minimal read-only setup points `--db-path` at a local DuckDB file. An in-memory development setup can add `--read-write` and `--allow-switch-databases`. For MotherDuck read-write access, use `--db-path md:` with `--read-write` and provide the MotherDuck token.

Read-only MotherDuck connections require a read-scaling token. Regular MotherDuck tokens require read-write mode. S3-backed DuckDB files can be addressed with an `s3://` path; the repository also documents S3 authentication under its environment-variable configuration.

The server can be configured in Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, and other MCP-compatible clients. Configuration is client-specific, but the core command uses `uvx mcp-server-motherduck` followed by the database and access flags.

## Tools and capabilities

- `execute_query`: Runs a DuckDB SQL query, including read or write statements allowed by the selected mode.
- `list_databases`: Shows databases available through the current connection setup.
- `list_tables`: Lists tables and views, optionally narrowed by database and schema.
- `list_columns`: Lists columns for a table or view, with optional database and schema selectors.
- `switch_database_connection`: Changes the active connection when database switching is enabled.

Results are limited by default to 1,024 rows or 50,000 characters. The limits can be changed with `--max-rows` and `--max-chars`.

## Limitations and notes

Read-only mode does not by itself provide complete isolation for third-party access: the local process can still access the filesystem and change DuckDB settings. The repository recommends considering the hosted MotherDuck Remote MCP service for production deployments involving third parties. The default database path is now `:memory:`, so MotherDuck users must specify `md:` explicitly.

_Full upstream README: https://allmcps.com/mcp/mcp-server-motherduck/readme_