mcp-server-motherduck
installs/mo · pypistarsforks
How to install mcp-server-motherduck?
motherduckdb/mcp-server-motherduck
$git clone https://github.com/motherduckdb/mcp-server-motherduck---
README.md
| 1 | <p align="center"> |
| 2 | <img src="src/mcp_server_motherduck/assets/duck_feet_square.png" alt="MotherDuck / DuckDB Local MCP Server" width="120"> |
| 3 | </p> |
| 4 | |
| 5 | <h1 align="center">DuckDB / MotherDuck Local MCP Server</h1> |
| 6 | |
| 7 | <p align="center"> |
| 8 | SQL analytics and data engineering for AI Assistants and IDEs. |
| 9 | </p> |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | Connect AI assistants to your data using DuckDB's powerful analytical SQL engine. Supports connecting to local DuckDB files, in-memory databases, S3-hosted databases, and MotherDuck. Allows executing SQL read- and write-queries, browsing database catalogs, and switching between different database connections on-the-fly. |
| 14 | |
| 15 | **Looking for a fully-managed remote MCP server for MotherDuck?** → [Go to the MotherDuck Remote MCP docs](https://motherduck.com/docs/sql-reference/mcp/) |
| 16 | |
| 17 | ### Remote vs Local MCP |
| 18 | |
| 19 | | | **[Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** | **Local MCP** (this repo) | |
| 20 | |---|---|---| |
| 21 | | **Hosting** | Hosted by MotherDuck | Runs locally/self-hosted | |
| 22 | | **Setup** | Zero-setup | Requires local installation | |
| 23 | | **Access** | Read-write supported | Read-write supported | |
| 24 | | **Local filesystem** | - | Query across local and remote databases, ingest data from / export data to local filesystem | |
| 25 | |
| 26 | > 📝 **Migrating from v0.x?** |
| 27 | > - **Read-only by default**: The server now runs in read-only mode by default. Add `--read-write` to enable write access. See [Securing for Production](#securing-for-production). |
| 28 | > - **Default database changed**: `--db-path` default changed from `md:` to `:memory:`. Add `--db-path md:` explicitly for MotherDuck. |
| 29 | > - **MotherDuck read-only requires read-scaling token**: MotherDuck connections in read-only mode require a [read-scaling token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#read-scaling-tokens). Regular tokens require `--read-write`. |
| 30 | |
| 31 | ## Quick Start |
| 32 | |
| 33 | **Prerequisites**: Install `uv` via `pip install uv` or `brew install uv` |
| 34 | |
| 35 | ### Connecting to In-Memory DuckDB (Dev Mode) |
| 36 | |
| 37 | ```json |
| 38 | { |
| 39 | "mcpServers": { |
| 40 | "DuckDB (in-memory, r/w)": { |
| 41 | "command": "uvx", |
| 42 | "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"] |
| 43 | } |
| 44 | } |
| 45 | } |
| 46 | ``` |
| 47 | |
| 48 | Full flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime. |
| 49 | |
| 50 | ### Connecting to a Local DuckDB File in Read-Only Mode |
| 51 | |
| 52 | ```json |
| 53 | { |
| 54 | "mcpServers": { |
| 55 | "DuckDB (read-only)": { |
| 56 | "command": "uvx", |
| 57 | "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"] |
| 58 | } |
| 59 | } |
| 60 | } |
| 61 | ``` |
| 62 | |
| 63 | Connects to a specific DuckDB file in read-only mode. Won't hold on to the file lock, so convenient to use alongside a write connection to the same DuckDB file. You can also connect to remote DuckDB files on S3 using `s3://bucket/path.duckdb` — see [Environment Variables](#environment-variables) for S3 authentication. If you're considering third-party access to the MCP, see [Securing for Production](#securing-for-production). |
| 64 | |
| 65 | ### Connecting to MotherDuck in Read-Write Mode |
| 66 | |
| 67 | ```json |
| 68 | { |
| 69 | "mcpServers": { |
| 70 | "MotherDuck (local, r/w)": { |
| 71 | "command": "uvx", |
| 72 | "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"], |
| 73 | "env": { |
| 74 | "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>" |
| 75 | } |
| 76 | } |
| 77 | } |
| 78 | } |
| 79 | ``` |
| 80 | |
| 81 | See [Command Line Parameters](#command-line-parameters) for more options, [Securing for Production](#securing-for-production) for deployment guidance, and [Troubleshooting](#troubleshooting) if you encounter issues. |
| 82 | |
| 83 | ## Client Setup |
| 84 | |
| 85 | | Client | Config Location | One-Click Install | |
| 86 | |--------|-----------------|-------------------| |
| 87 | | **Claude Desktop** | Settings → Developer → Edit Config | [.mcpb (MCP Bundle)](https://github.com/motherduckdb/mcp-server-motherduck/releases/latest/download/mcp-server-motherduck.mcpb) | |
| 88 | | **Claude Code** | Use CLI commands below | - | |
| 89 | | **Codex CLI** | Use CLI commands below or `~/.codex/config.toml` | - | |
| 90 | | **Gemi |
People who liked this also viewed
6 picksType
- mcp-databricks-serverModel Context Protocol (MCP) server for Databricks that empowers AI agents to autonomously interact with Unity Catalog metadata. Enables data discovery, lineage analysis, and intelligent SQL execution. Agents explore catalogs/schemas/tables, understand relationships, discover notebooks/jobs, and execute queries - greatly reducing ad-hoc query time.MCP ServersMar 2026
- mcp-server-qdrantAn official Qdrant Model Context Protocol (MCP) server implementationMCP ServersJul 2026
- mcp-server-odooModel Context Protocol (MCP) server that enables AI assistants to securely interact with Odoo ERP systems through standardized resources and tools for data retrieval and manipulation.MCP ServersJul 2026
- mongodb-mcp-serverA Model Context Protocol server to connect to MongoDB databases and MongoDB Atlas Clusters.MCP ServersJul 2026
- postgres-mcp-serverMCP (Model Context Protocol) Server for postgres DatabaseMCP ServersJul 2025
- mcp-google-sheetsThis MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.MCP ServersMay 2026
