2497 Cross Platform Notes B77d95b9

mcp-server-motherduck — Cross-Platform Path Configuration

Verified against v1.0.1 source code read from motherduckdb/mcp-server-motherduck via GitHub API (2026-02-22).

The Core Problem

MCP client mcpServers JSON configs pass args as a string array. The array is passed to the subprocess directly — no shell interprets it. Therefore:

• ~ is NOT expanded to the home directory
• $HOME is NOT substituted
• %USERPROFILE% is NOT substituted

The mcp-server-motherduck source code also performs no expansion. Evidence: zero matches for expanduser, expandvars, os.path.expand* in __init__.py and database.py (grep verified 2026-02-22).

Solution Patterns by Client

Pattern 1: MCP_DB_PATH Environment Variable (Recommended)

The --db-path option reads from MCP_DB_PATH envvar (source: __init__.py line 51, envvar="MCP_DB_PATH").

The MCP client host process inherits the OS environment. Setting MCP_DB_PATH in the system or user environment means the args array never needs a path.

{
  "mcpServers": {
    "duckdb": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--read-write"],
      "env": {
        "MCP_DB_PATH": "/Users/jane/data/my.duckdb"
      }
    }
  }
}

Each user/machine sets MCP_DB_PATH in their profile. The checked-in JSON stays static.

Pattern 2: Absolute Path Hardcoded Per Machine

Acceptable when the config is per-machine (not shared). Use the absolute path directly in args:

{
  "args": ["mcp-server-motherduck", "--db-path", "/Users/jane/data/my.duckdb", "--read-write"]
}

Pattern 3: In-Memory (No Path Required)

When persistent storage is not needed:

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

Note: --read-write is mandatory with :memory:. Omitting it causes a UsageError at startup.

Pattern 4: MotherDuck (No Local Path)

When using MotherDuck cloud storage, no local path is needed:

{
  "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
  "env": {
    "motherduck_token": "<TOKEN>"
  }
}

Windows-Specific: HOME and DuckDB Extensions

DuckDB uses the HOME environment variable to locate its extensions directory. On Windows, HOME is not set by default (Windows uses USERPROFILE).

The --home-dir flag sets os.environ["HOME"] for the server process (source: database.py lines 63-64):

if home_dir:
    os.environ["HOME"] = home_dir

Limitation: --home-dir must be an absolute path in the args array (same problem as --db-path). Since it also cannot use tilde, the value must be literal.

Workaround options:

1. Set HOME in the system environment before launching the MCP client. DuckDB will find it without --home-dir.
2. Pass --home-dir C:\Users\username as a literal absolute path in the args array.
3. Set HOME in the env section of the MCP config:

{
  "env": {
    "HOME": "C:\\Users\\username",
    "MCP_DB_PATH": "C:\\Users\\username\\data\\my.duckdb"
  }
}

Environment Variable Precedence

For --db-path / MCP_DB_PATH:

1. CLI flag --db-path takes precedence over MCP_DB_PATH envvar (Click behavior: envvar is fallback when CLI flag not provided)
2. If neither is provided, default is :memory:

For MotherDuck token:

1. --motherduck-token CLI flag
2. motherduck_token environment variable
3. MOTHERDUCK_TOKEN environment variable

Source: __init__.py line 58: envvar=["motherduck_token", "MOTHERDUCK_TOKEN"] (Click checks in order).

Client-Specific Notes

Claude Code

Supports env section in mcpServers config. MCP_DB_PATH in env works reliably. Claude Code issue #1254 reports that env vars from env section were not always passed in earlier versions — verify on current Claude Code version.

Source: https://github.com/anthropics/claude-code/issues/1254 (referenced in web search, 2026-02-22)

Claude Desktop

JSON config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). The env section is supported. Set MCP_DB_PATH there.

Cursor

Settings -> MCP -> Add new global MCP server. Uses JSON with command, args, env structure. env section is supported.

OpenCode / Codex

Both support env section alongside args. MCP_DB_PATH in env is the correct approach.

What Does NOT Work

Sources

• src/mcp_server_motherduck/__init__.py read via gh api repos/motherduckdb/mcp-server-motherduck/contents/... (2026-02-22)
• src/mcp_server_motherduck/database.py read via gh api (2026-02-22)
• README.md read via gh api (2026-02-22)
• https://github.com/motherduckdb/mcp-server-motherduck (official repository, accessed 2026-02-22)