mcp -motherduck

This MCP server enables AI assistants and IDEs to query and manage DuckDB databases locally or against MotherDuck. It exposes tools to execute SQL read and write queries, inspect catalogs, list tables and columns, and switch between multiple database connections at runtime. The in-memory option is ideal for quick experimentation and development, while the local file option lets you work with existing DuckDB files. The MotherDuck option connects to MotherDuck using a token and provides read-write access to your MotherDuck databases, with the ability to switch between local and remote datasets during a session. You can invoke the server via uvx (Python/uv) and pass commands like --db-path, --read-write, and --allow-switch-databases to tailor access and capabilities per connection. All client tools expect a JSON-based MCP config, enabling seamless integration with IDEs, Claude/Codex, Cursor, VS Code, and other MCP clients. Use the Tools section to execute queries, enumerate databases, and explore schemas across attached data sources.

Prerequisites:

• Python 3.8+ and uv installed (pip install uv)
• Internet access to install Python packages if needed
• Optional: MotherDuck account and token for MotherDuck connections

1. Install uv (Python UV) globally:

pip install uv

2. Verify installation:

uv --version

3. Ensure you have the MCP server package (mcp-server-motherduck) accessible in your PATH or project directory. The server is run via uvx as shown in the configuration.
4. Prepare a DuckDB database (optional for local file path): create or locate a .duckdb file to connect to, or use an in-memory database with the dev/debug setup.
5. If using MotherDuck, obtain a read-scaling token and set it via the environment variable motherduck_token in your MCP config or shell environment.
6. Run your MCP config with your client, or start the MCP server locally by following your client’s instructions for loading an API config (the examples in this repo show the exact JSON blocks to paste into your client).

Tips and common issues:

• Read-only vs read-write: By default the server may run in read-only mode. Add --read-write to enable writes. For MotherDuck, ensure your token has appropriate permissions.
• Database paths: Use :memory: for in-memory operation. Use md: for MotherDuck connections. Absolute paths are required for local DuckDB files when using read-only mode.
• Switching databases at runtime: Include --allow-switch-databases where supported; this enables dynamic switching between connected databases without restarting the MCP server.
• Security: For production deployments, use proper authentication, tokens, and restricted file access. Consider MotherDuck Remote MCP for zero-setup deployments and SaaS-mode access control.
• Client compatibility: MCP results are returned as JSON and can be consumed by Claude, Codex, Cursor, VS Code, and other MCP clients. Ensure the client config matches the formats demonstrated in the Quick Start section of the README.