Client Setup - MCP Server MotherDuck

Supported Clients

MCP Server MotherDuck works with any MCP-compatible client. Below are setup instructions for popular clients:

Client	Config Location	One-Click Install
Claude Desktop	Settings → Developer → Edit Config	Download .mcpb Bundle
Claude Code	Use CLI commands	-
Codex CLI	Use CLI commands	-
Cursor	Settings → MCP → Add new global MCP server	Install in Cursor
VS Code	`Ctrl+Shift+P` → “Preferences: Open User Settings (JSON)“	Install with UV

Prerequisites: Install uv package manager via pip install uv or brew install uv

Configuration File Setup

Most MCP clients use a JSON configuration file. The configuration structure is similar across clients, with minor variations in file location.

Basic Configuration Structure

{
  "mcpServers": {
    "<server-name>": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "<parameters>..."],
      "env": {
        "<ENV_VAR>": "<value>"
      }
    }
  }
}

Client-Specific Setup

Claude Desktop
VS Code
Cursor
Claude Code CLI
Codex CLI

Claude Desktop Configuration

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Access via UI:

Open Claude Desktop
Go to Settings → Developer
Click “Edit Config”

Example 1: In-Memory Database (Dev Mode)

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

Example 2: Local DuckDB File (Read-Only)

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/absolute/path/to/your.duckdb"
      ]
    }
  }
}

Example 3: MotherDuck (Read-Write)

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

One-Click Installation

Download and double-click the .mcpb bundle file to automatically install in Claude Desktop.

After updating the config file, restart Claude Desktop for changes to take effect.

VS Code Configuration

Config file location:

macOS/Linux: ~/.vscode/settings.json or workspace .vscode/settings.json
Windows: %APPDATA%\Code\User\settings.json or workspace .vscode\settings.json

Access via UI:

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
Type “Preferences: Open User Settings (JSON)”
Add MCP configuration under mcpServers key

Example Configuration

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", ":memory:",
        "--read-write",
        "--allow-switch-databases"
      ]
    },
    "MotherDuck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "md:"
      ],
      "env": {
        "motherduck_token": "<YOUR_TOKEN>"
      }
    }
  }
}

One-Click Installation

Click the badge below to automatically install:

Cursor Configuration

Config file location:

macOS: ~/Library/Application Support/Cursor/User/settings.json
Windows: %APPDATA%\Cursor\User\settings.json
Linux: ~/.config/Cursor/User/settings.json

Access via UI:

Open Cursor
Go to Settings → MCP
Click “Add new global MCP server”

Example Configuration

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

One-Click Installation

Click the image below to install directly in Cursor:

Claude Code CLI Commands

Claude Code uses CLI commands to add MCP servers instead of editing JSON files.

In-Memory DuckDB (Dev Mode)

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

Local DuckDB File (Read-Only)

claude mcp add --scope user duckdb \
  --transport stdio \
  -- uvx mcp-server-motherduck \
  --db-path /absolute/path/to/db.duckdb

MotherDuck (Read-Write)

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

List Configured Servers

claude mcp list

Remove a Server

claude mcp remove duckdb

Codex CLI Commands

Codex uses CLI commands similar to Claude Code for MCP server configuration.

In-Memory DuckDB (Dev Mode)

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

Local DuckDB File (Read-Only)

codex mcp add duckdb \
  -- uvx mcp-server-motherduck \
  --db-path /absolute/path/to/db.duckdb

MotherDuck (Read-Write)

codex mcp add motherduck \
  --env motherduck_token=YOUR_TOKEN \
  -- uvx mcp-server-motherduck \
  --db-path md: \
  --read-write

Advanced Configuration Examples

Multiple Database Connections

You can configure multiple MCP server instances to connect to different databases simultaneously:

{
  "mcpServers": {
    "Production MotherDuck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "md:production_db"
      ],
      "env": {
        "motherduck_token": "<PROD_TOKEN>",
        "MCP_MAX_ROWS": "1024",
        "MCP_QUERY_TIMEOUT": "30"
      }
    },
    "Staging MotherDuck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "md:staging_db",
        "--read-write"
      ],
      "env": {
        "motherduck_token": "<STAGING_TOKEN>"
      }
    },
    "Local Analytics": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/Users/you/data/analytics.duckdb",
        "--read-write"
      ]
    },
    "S3 Data Lake": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "s3://my-data-lake/warehouse.duckdb"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<YOUR_KEY_ID>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET>",
        "AWS_DEFAULT_REGION": "us-west-2"
      }
    }
  }
}

Development Configuration with Initialization SQL

{
  "mcpServers": {
    "DuckDB Dev": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", ":memory:",
        "--read-write",
        "--allow-switch-databases",
        "--init-sql", "INSTALL httpfs; LOAD httpfs; INSTALL spatial; LOAD spatial;"
      ]
    }
  }
}

HTTP Transport Configuration

{
  "mcpServers": {
    "DuckDB HTTP": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--transport", "http",
        "--host", "127.0.0.1",
        "--port", "8000",
        "--db-path", "md:"
      ],
      "env": {
        "motherduck_token": "<YOUR_TOKEN>"
      }
    }
  }
}

Running from Source (Development)

For contributors or those testing local changes:

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

Common Configuration Patterns

Read-Only Production Database

{
  "mcpServers": {
    "Production (Read-Only)": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "md:production_db",
        "--motherduck-saas-mode"
      ],
      "env": {
        "motherduck_token": "<READ_SCALING_TOKEN>",
        "MCP_MAX_ROWS": "1024",
        "MCP_QUERY_TIMEOUT": "30"
      }
    }
  }
}

Local File with Custom Limits

{
  "mcpServers": {
    "Local Analytics": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/Users/you/data/analytics.duckdb",
        "--read-write"
      ],
      "env": {
        "MCP_MAX_ROWS": "5000",
        "MCP_MAX_CHARS": "100000",
        "MCP_QUERY_TIMEOUT": "60",
        "MCP_EPHEMERAL_CONNECTIONS": "false"
      }
    }
  }
}

Troubleshooting

Common Issues

spawn uvx ENOENT

The client cannot find the uvx command.Solution: Specify the full path to uvx:

# Find uvx path
which uvx
# Returns: /Users/you/.local/bin/uvx

{
  "mcpServers": {
    "DuckDB": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write"]
    }
  }
}

Database file is locked

Another process has a write lock on the DuckDB file.Solutions:

Ensure --ephemeral-connections is enabled (default for read-only)
Close other connections to the database
Don’t use --read-write if you only need read access

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/path/to/db.duckdb"
      ],
      "env": {
        "MCP_EPHEMERAL_CONNECTIONS": "true"
      }
    }
  }
}

In-memory database requires --read-write

You’re trying to use :memory: without the --read-write flag.Solution: Add --read-write flag:

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", ":memory:",
        "--read-write"
      ]
    }
  }
}

MotherDuck authentication failed

Invalid or missing MotherDuck token.Solutions:

Verify your token is correct
For read-only mode, use a read-scaling token
For read-write mode, use a regular access token

{
  "mcpServers": {
    "MotherDuck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "md:",
        "--read-write"
      ],
      "env": {
        "motherduck_token": "<VALID_TOKEN>"
      }
    }
  }
}

Server not appearing in client

The client hasn’t detected the configuration changes.Solution: Restart the client application completely (not just reload window).

Next Steps

Review Command Line Parameters for detailed parameter documentation
Check Environment Variables for alternative configuration methods
See Quick Start for usage examples
Explore API Reference for available tools

Get Started

Configuration

Guides

Examples

​Supported Clients

​Configuration File Setup

​Basic Configuration Structure

​Client-Specific Setup

​Claude Desktop Configuration

​Example 1: In-Memory Database (Dev Mode)

​Example 2: Local DuckDB File (Read-Only)

​Example 3: MotherDuck (Read-Write)

​One-Click Installation

​VS Code Configuration

​Example Configuration

​One-Click Installation

​Cursor Configuration

​Example Configuration

​One-Click Installation

​Claude Code CLI Commands

​In-Memory DuckDB (Dev Mode)

​Local DuckDB File (Read-Only)

​MotherDuck (Read-Write)

​List Configured Servers

​Remove a Server

​Codex CLI Commands

​In-Memory DuckDB (Dev Mode)

​Local DuckDB File (Read-Only)

​MotherDuck (Read-Write)

​Advanced Configuration Examples

​Multiple Database Connections

​Development Configuration with Initialization SQL

​HTTP Transport Configuration

​Running from Source (Development)

​Common Configuration Patterns

​Read-Only Production Database

​Local File with Custom Limits

​Troubleshooting

​Common Issues

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Supported Clients

Configuration File Setup

Basic Configuration Structure

Client-Specific Setup

Claude Desktop Configuration

Example 1: In-Memory Database (Dev Mode)

Example 2: Local DuckDB File (Read-Only)

Example 3: MotherDuck (Read-Write)

One-Click Installation

VS Code Configuration

Example Configuration

One-Click Installation

Cursor Configuration

Example Configuration

One-Click Installation

Claude Code CLI Commands

In-Memory DuckDB (Dev Mode)

Local DuckDB File (Read-Only)

MotherDuck (Read-Write)

List Configured Servers

Remove a Server

Codex CLI Commands

In-Memory DuckDB (Dev Mode)

Local DuckDB File (Read-Only)

MotherDuck (Read-Write)

Advanced Configuration Examples

Multiple Database Connections

Development Configuration with Initialization SQL

HTTP Transport Configuration

Running from Source (Development)

Common Configuration Patterns

Read-Only Production Database

Local File with Custom Limits

Troubleshooting

Common Issues

Next Steps

Additional Resources