mcp-server-motherduck

Connect to MotherDuck with read-write access. You must provide your MotherDuck token via the motherduck_token environment variable.

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

You can build and run the server using Docker. By default, it runs with an in-memory DuckDB. To connect to MotherDuck, pass the token as an environment variable and override the command to use the HTTP transport.

# Build and run with default in-memory DuckDB on port 8000
docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

# Connect to MotherDuck via HTTP
docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

For development with full flexibility, connect to an in-memory DuckDB instance. This mode provides read-write access and allows switching between different databases (local files, S3, or MotherDuck) at runtime using the --allow-switch-databases flag.

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

The server can be integrated into various MCP-compatible clients. Most clients require adding a JSON configuration block.

Common Client Config Locations:

• Claude Desktop: Settings → Developer → Edit Config
• Cursor: Settings → MCP → Add new global MCP server
• VS Code: User Settings (JSON)
• Kiro: ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json (project)

For CLI-based clients like Claude Code, Codex, or Gemini, use the specific mcp add commands provided in the documentation.

Connect to a specific local DuckDB file in read-only mode. This mode does not hold a file lock, allowing you to use it alongside other write connections to the same file. You can also use S3 URLs (e.g., s3://bucket/path.duckdb) for remote files.

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

The DatabaseClient supports connecting to S3 via s3:// paths. When an S3 path is provided, the client automatically:

1. Creates an in-memory DuckDB connection.
2. Installs and loads the httpfs extension.
3. Configures S3 credentials using CREATE SECRET based on available environment variables:
   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • AWS_SESSION_TOKEN (if present, uses credential_chain provider)
   • AWS_DEFAULT_REGION (defaults to us-east-1)
   • AWS_ENDPOINT
4. Attaches the S3 path as a database named s3db (typically in READ_ONLY mode).

If you are working with an in-memory database (:memory:) and want to save your work to a persistent file, use the ATTACH and COPY commands:

1. Attach a new file-based database.
2. Copy data from the memory database to the attached database.
3. Detach the database when finished.

-- Attach a new file-based database
ATTACH '/path/to/my_database.db' AS my_db;

-- Copy all data from memory to the file
COPY FROM DATABASE memory TO my_db;

-- Optionally detach when done
DETACH my_db;

If you encounter issues while running the server, check the following common scenarios:

• spawn uvx ENOENT error: The system cannot find the uvx executable. Resolve this by specifying the full absolute path to uvx. You can find the path by running which uvx in your terminal.
• File locked error: This typically happens when a database file is already in use. Ensure that --ephemeral-connections is enabled (this is the default setting: true) and verify that you are not attempting to connect in read-write mode while another process holds a lock.

To run the server directly from the source code for development purposes, configure your MCP client (e.g., Claude Desktop) with the following JSON configuration. Replace /path/to/mcp-server-motherduck with your actual local path and <YOUR_MOTHERDUCK_TOKEN> with your actual token.

This configuration uses uv to run the server in an in-memory DuckDB mode (--db-path md:).

{
  "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>"
      }
    }
  }
}

The server exposes the following tools to the AI assistant. All tools return JSON. By default, results are limited to 1024 rows or 50,000 characters (configurable via --max-rows and --max-chars).

*Note: switch_database_connection requires the --allow-switch-databases flag to be enabled.