home / mcp / duckdb / motherduck local mcp server

DuckDB / MotherDuck Local MCP Server

Provides local SQL analytics and data access to DuckDB and MotherDuck via an MCP server for AI assistants and IDEs.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "motherduckdb-mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:",
        "--read-write",
        "--allow-switch-databases"
      ],
      "env": {
        "HOME": "/home/user",
        "motherduck_token": "YOUR_TOKEN",
        "AWS_ACCESS_KEY_ID": "AKIA...",
        "AWS_SESSION_TOKEN": "token",
        "AWS_DEFAULT_REGION": "us-east-1",
        "AWS_SECRET_ACCESS_KEY": "secret"
      }
    }
  }
}

You can run a local MCP server that connects to DuckDB and MotherDuck, enabling you to run SQL queries, browse databases, and switch between different data sources from your development tools. This server supports in-memory, local DuckDB files, remote S3-hosted databases, and MotherDuck, and it enables read-write or read-only access depending on how you configure it.

How to use

Connect your MCP client to one of the available server configurations to start querying your data sources. You can run the MCP in memory for development, connect to a local DuckDB file in read-only mode for safe experimentation, or connect to MotherDuck in read-write mode for full interaction with your data. You can switch between databases at runtime and ingest or export data as needed.

How to install

Prerequisites: Install the universal data transport tool uv on your system.

Install uv
- macOS: `brew install uv`
- Linux: `pip install uv`
- Windows: use your preferred Python package manager to install uv

Start from one of the available configurations below by running the appropriate command in your terminal. Choose the configuration that matches your data source and desired access mode.

# In-Memory DuckDB (Dev Mode) - Read/Write with database switching
uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

# Local DuckDB File (Read-Only)
uvx mcp-server-motherduck --db-path /absolute/path/to/your.duckdb

# MotherDuck (Local, Read-Write)
uvx mcp-server-motherduck --db-path md: --read-write
export motherduck_token=<YOUR_MOTHERDUCK_TOKEN>

Additional sections

Security and deployment notes: For production deployments with third-party access, prefer MotherDuck Remote MCP for zero-setup, read-write capability, and hosted reliability. If you self-host, use a service account with read-scaling tokens and enable SaaS mode to restrict local file access. You can also apply security settings via startup SQL to DuckDB when running locally.

Tools and end-user capabilities

The server exposes a set of tools to interact with your databases from the MCP client. These tools return structured results in JSON and are designed to help you run queries, explore schemas, and move between databases.

Available tools

execute_query

Execute a SQL query against the connected DuckDB or MotherDuck database and return results in JSON.

list_databases

List all connected databases, useful when multiple sources like MotherDuck or S3 are attached.

list_tables

List tables and views in the current database; supports optional database and schema filters.

list_columns

List columns for a given table or view; can accept database and schema hints.

switch_database_connection

Switch the active database connection to another path or source (requires --allow-switch-databases).