Troubleshooting

This guide helps you resolve common issues when setting up and using MCP Server MotherDuck.

Common Issues

spawn uvx ENOENT

Error:

Error: spawn uvx ENOENT

Cause: The MCP client cannot find the uvx command in your system PATH.Solution: Specify the full path to uvx in your configuration.

Find the full path to uvx:
```
which uvx
```
Example output: /usr/local/bin/uvx or /Users/username/.local/bin/uvx

Update your MCP configuration with the full path:

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

Alternative: Install uv if not already installed:

# Using pip
pip install uv

# Using Homebrew (macOS)
brew install uv

File Locked / Database is Locked

Error:

Error: database is locked
Error: cannot open database file: file is locked

Cause: Another process has a write lock on the database file, or ephemeral connections are disabled.Solution 1: Enable ephemeral connections (default for read-only):

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/path/to/your.duckdb"
        // ephemeral connections are enabled by default
      ]
    }
  }
}

Solution 2: Check if you’re in read-write mode:

// If you have --read-write, remove it for concurrent access
{
  "args": [
    "mcp-server-motherduck",
    "--db-path", "/path/to/your.duckdb"
    // Remove --read-write flag
  ]
}

Solution 3: Close other connections to the database:

Check for other MCP servers connected to the same file
Close any DuckDB CLI sessions
Close applications with open connections to the file

Ephemeral connections are turned on by default for read-only local files. Make sure you haven’t disabled them with --no-ephemeral-connections.

MotherDuck Token Issues

Error:

Error: Please set the `motherduck_token` or `MOTHERDUCK_TOKEN` as an environment variable

Cause: MotherDuck token is not configured.Solution: Set the token in your MCP configuration:

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

Alternative: Set as system environment variable:

# macOS/Linux
export motherduck_token="your_token_here"

# Windows (PowerShell)
$env:motherduck_token="your_token_here"

The server checks for both motherduck_token and MOTHERDUCK_TOKEN environment variables (case-insensitive).

Read-Scaling Token Required

Error:

Error: The --read-only flag with MotherDuck requires a read-scaling token.
You appear to be using a read/write token. Please use a read-scaling token instead.

Cause: You’re using a regular MotherDuck token in read-only mode, which requires a read-scaling token.Solution 1: Use read-write mode with your regular token:

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

Solution 2: Create and use a read-scaling token:

Create a read-scaling token in MotherDuck:
- Visit MotherDuck Console
- Go to Settings → Tokens
- Create a new read-scaling token

Use the read-scaling token:

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

Read-scaling tokens provide read-only access and are optimized for analytics workloads. Learn more in the MotherDuck documentation.

In-Memory Database Requires --read-write

Error:

Error: In-memory databases require the --read-write flag

Cause: DuckDB doesn’t support read-only mode for in-memory databases (:memory:).Solution: Add the --read-write flag:

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

In-memory databases are temporary by nature, so write access doesn’t pose the same risks as persistent databases.

S3 Connection Issues

Error:

Error: Failed to attach S3 database
Error: Unable to connect to S3 endpoint

Cause: Missing AWS credentials or incorrect S3 configuration.Solution: Provide AWS credentials in environment variables:

{
  "mcpServers": {
    "DuckDB S3": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "s3://bucket/path.duckdb"],
      "env": {
        "AWS_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET_KEY>",
        "AWS_DEFAULT_REGION": "us-east-1"
      }
    }
  }
}

For IAM roles/session tokens:

{
  "env": {
    "AWS_SESSION_TOKEN": "<YOUR_SESSION_TOKEN>",
    "AWS_DEFAULT_REGION": "us-east-1"
  }
}

Troubleshooting checklist:

Verify S3 bucket exists and is accessible
Check AWS credentials are correct
Ensure IAM permissions allow S3 access
Verify S3 bucket region matches AWS_DEFAULT_REGION
Check S3 path is correct: s3://bucket-name/path/to/file.duckdb

Query Timeout

Error:

Error: Query execution timed out after X seconds

Cause: Query exceeded the configured timeout limit.Solution 1: Increase the timeout:

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/path/to/db.duckdb",
        "--query-timeout", "120"  // 120 seconds
      ]
    }
  }
}

Solution 2: Disable timeout (use with caution):

{
  "args": [
    "mcp-server-motherduck",
    "--db-path", "/path/to/db.duckdb",
    "--query-timeout", "-1"  // Disable timeout
  ]
}

Solution 3: Optimize the query:

Add indexes to frequently queried columns
Use LIMIT clause to reduce result set size
Filter data earlier in the query
Check query execution plan with EXPLAIN

Results Truncated

Warning:

Results limited to 1,024 rows. Query returned more data.
Results limited to X rows due to 50KB output size limit.

Cause: Query results exceed configured limits.Solution: Adjust result limits:

{
  "mcpServers": {
    "DuckDB": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path", "/path/to/db.duckdb",
        "--max-rows", "5000",     // Increase row limit
        "--max-chars", "100000"   // Increase character limit
      ]
    }
  }
}

Very large limits may cause performance issues or memory problems. Use SQL LIMIT clauses in your queries for better control.

Alternative: Use SQL LIMIT in your query:

SELECT * FROM large_table LIMIT 100;

Cannot Switch Databases

Error:

Tool 'switch_database_connection' not found

Cause: Database switching is disabled by default.Solution: Enable the --allow-switch-databases flag:

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

Only enable --allow-switch-databases in trusted environments. This gives the AI assistant access to any database path it can construct.

Init SQL Execution Failed

Error:

Error: Init SQL execution failed: [error details]

Cause: The SQL provided in --init-sql contains syntax errors or invalid commands.Solution 1: Verify SQL syntax:

-- Test your init SQL in DuckDB CLI first
SET enable_external_access = false;
SET memory_limit = '4GB';

Solution 2: Check file path (if using file):

{
  "args": [
    "mcp-server-motherduck",
    "--db-path", "/path/to/db.duckdb",
    "--init-sql", "/absolute/path/to/init.sql"  // Use absolute path
  ]
}

Solution 3: Use inline SQL string:

{
  "args": [
    "mcp-server-motherduck",
    "--db-path", "/path/to/db.duckdb",
    "--init-sql", "SET memory_limit = '4GB'; SET enable_external_access = false;"
  ]
}

Migration Issues (v0.x to v1.0+)

If you’re upgrading from version 0.x, be aware of these breaking changes:

Read-Only by Default

Old behavior (v0.x): Write access by default
New behavior (v1.0+): Read-only by default Migration:

// Add --read-write to enable write access
{
  "args": [
    "mcp-server-motherduck",
    "--db-path", ":memory:",
    "--read-write"  // Add this
  ]
}

Default Database Changed

Old behavior (v0.x): Default --db-path was md:
New behavior (v1.0+): Default --db-path is :memory: Migration:

// Explicitly specify md: for MotherDuck
{
  "args": [
    "mcp-server-motherduck",
    "--db-path", "md:",  // Add this explicitly
    "--read-write"
  ]
}

MotherDuck Read-Only Requires Read-Scaling Token

New requirement: MotherDuck connections in read-only mode require a read-scaling token. Migration: Either:

Use --read-write with regular token
Create a read-scaling token for read-only access

See Read-Scaling Token Required above.

Getting Help

If you’re still experiencing issues:

Check the logs: Look for detailed error messages in your MCP client logs
Verify configuration: Ensure your JSON configuration is valid
Test connection: Try connecting with a simple in-memory database first
GitHub Issues: Search existing issues or create a new one at github.com/motherduckdb/mcp-server-motherduck

Minimal Reproduction Configuration

When reporting issues, try this minimal configuration first:

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

If this works, gradually add your specific configuration options to identify the issue.

Useful Commands

Verify Installation

# Check if uv is installed
which uv
uv --version

# Check if uvx is available
which uvx

# Test MCP server installation
uvx mcp-server-motherduck --help

Test DuckDB Connection

# Test with DuckDB CLI
python -c "import duckdb; print(duckdb.connect(':memory:').execute('SELECT 42').fetchone())"

Check Environment Variables

# macOS/Linux
env | grep -i motherduck
env | grep -i aws

# Windows (PowerShell)
Get-ChildItem Env: | Where-Object {$_.Name -like '*motherduck*'}
Get-ChildItem Env: | Where-Object {$_.Name -like '*aws*'}

Get Started

Configuration

Guides

Examples

Common Issues

Migration Issues (v0.x to v1.0+)

Read-Only by Default

Default Database Changed

MotherDuck Read-Only Requires Read-Scaling Token

Getting Help

Minimal Reproduction Configuration

Useful Commands

Verify Installation

Test DuckDB Connection

Check Environment Variables

Resources

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

Examples

​Common Issues

​Migration Issues (v0.x to v1.0+)

​Read-Only by Default

​Default Database Changed

​MotherDuck Read-Only Requires Read-Scaling Token

​Getting Help

​Minimal Reproduction Configuration

​Useful Commands

​Verify Installation

​Test DuckDB Connection

​Check Environment Variables

​Resources

Build docs developers (and LLMs) love

Common Issues

Migration Issues (v0.x to v1.0+)

Read-Only by Default

Default Database Changed

MotherDuck Read-Only Requires Read-Scaling Token

Getting Help

Minimal Reproduction Configuration

Useful Commands

Verify Installation

Test DuckDB Connection

Check Environment Variables

Resources