DuckDB MCP setup: local file and MotherDuck access

Prepare a copy of a small DuckDB file containing known test data. Note its full path, one table name and one expected value. Keep the original file separate while you establish the connection.

File, memory or MotherDuck?

The MotherDuck project provides mcp-server-motherduck for local DuckDB and MotherDuck. Its documented defaults are a memory database and read-only access. Set --db-path to your existing file; the example does not enable writes or database switching.

Local VS Code example

Install uv and save this as .vscode/mcp.json. Replace the absolute file path with your test copy. On Windows, use an absolute path with JSON-compatible escaping, as described in the Windows guide.

{
  "servers": {
    "duckdb": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/ABSOLUTE/PATH/test.duckdb",
        "--max-rows",
        "20",
        "--query-timeout",
        "30"
      ]
    }
  }
}

First read, then compare

1. Start the server and inspect the available tools. If startup fails, verify the uvx executable and the file path separately.

2. List tables and confirm the prepared table is present. An empty list can indicate the wrong file or database.

3. Read the known row with an explicit column list and a small LIMIT. Compare values with the original note.

4. Close the client, reconnect and repeat the read against the same file. Record the package version and path used.

MotherDuck is a separate connection

MotherDuck uses --db-path md: and a token. The project documents a read-scaling token for read-only connections. A regular token requires the write-enabled mode. Resolve the token type before adapting the local example; do not add --read-write merely to clear an authentication error.

Read-only database access is not a filesystem sandbox. DuckDB can access resources beyond ordinary tables depending on its configuration. Review its security settings before making a server available to others. Use the permissions planner for the intended scope.

Find declared packages and sources in the DuckDB registry search or compare the SQLite setup for a different local database.

Document the path and data snapshot

A path is useful evidence only when you know which process resolves it. If your editor runs in a container, a remote environment or WSL, inspect the file visible in that environment. A file with the same name on your desktop is not sufficient evidence. Record file size, modification time and the expected table. Work from a copy when other applications are changing the data at the same time. Compare results against an unchanged snapshot and repeat the same small query after restarting the client. This separates selecting the wrong file from a problem in the query itself.

Why do I see no tables?

Check the explicit database path. A memory database is different from your existing file.

Does a local file need a MotherDuck token?

The local example does not use a MotherDuck connection or token.

Why is --read-write missing?

The first test is a read. Enable write access only when the intended workflow requires it.

Does read-only restrict all local file access?

No. Review DuckDB security controls and the permissions of the running process.

Vendor documentation checked on 2 October 2026. No authenticated account test.

1. MotherDuck: MCP server
   Show retrieval command

   curl -s https://github.com/motherduckdb/mcp-server-motherduck
2. DuckDB: Securing DuckDB
   Show retrieval command

   curl -s https://duckdb.org/docs/stable/operations_manual/securing_duckdb/overview
3. VS Code: MCP configuration
   Show retrieval command

   curl -s https://code.visualstudio.com/docs/agent-customization/mcp-servers

All posts