motherduckdb/mcp-server-motherduck

DuckDB / MotherDuck Local MCP Server – Quick Overview

What it is – A tiny, self‑hosted server that speaks the MCP (Model‑Chat‑Protocol) used by AI‑assistant tools (Claude, Gemini, Cursor, etc.). It wraps DuckDB – a fast, embeddable analytical SQL engine – and lets those assistants run SQL against:

• a local DuckDB file,
• an in‑memory DuckDB instance (great for dev),
• a DuckDB file stored on S3, or
• a MotherDuck cloud database (md:).

Why it matters for AI – Modern AI assistants need up‑to‑date data to answer questions or write code. By exposing DuckDB via MCP, the assistant can issue normal SQL (SELECT …) and get JSON results back, all without leaving the chat UI.

---

Core Features (as described in the README)

Feature	Details
SQL engine	Uses DuckDB’s analytical SQL dialect; supports read‑write queries.
Multiple back‑ends	Local file, in‑memory, S3‑hosted DuckDB, or MotherDuck (md:).
MCP‑compatible	Works with any client that implements the MCP spec (Claude Desktop/Code, Gemini, Cursor, Codex, Kiro, etc.).
Transport options	stdio (default, for CLI‑based clients) or HTTP (--transport http).
Dynamic DB switching	With --allow-switch-databases, a tool can change the underlying DB at runtime.
Security controls	Read‑only mode, optional token‑based MotherDuck auth, SaaS‑mode flag, and DuckDB‑level hardening via --init-sql.
Docker ready	Official Dockerfile; runs on port 8000, supports env‑vars for credentials.
Tooling	Built‑in JSON‑returning tools: execute_query, list_databases, list_tables, list_columns, switch_database_connection.
Limits	Default caps: 1 024 rows / 50 000 characters per response (configurable).

---

Typical Use‑Case Flow

1. Install uv (a Python package manager) – pip install uv.
2. Start the server with a single command, e.g.:

   uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
   

   This launches an in‑memory DuckDB that the assistant can read and write.
3. Configure the AI client – add a JSON snippet (shown in the README) to the client’s MCP config. The client then talks to the server via stdio or HTTP.
4. Run queries – the assistant calls the execute_query tool, receives JSON rows, and can iterate, join, or visualise the data.
5. Production – for external users, the README advises using MotherDuck’s hosted Remote MCP or securing the self‑hosted server with read‑only mode, service‑account tokens, and DuckDB hardening.

---

How to Get Started (Step‑by‑Step)

1. Prerequisite – Install uv.
2. Pick a backend – memory (:memory:), local file (/path/to.db), S3 (s3://bucket/file.duckdb), or MotherDuck (md:).
3. Run – Example for a local file, read‑only:

   uvx mcp-server-motherduck --db-path /abs/path/to.db
   

4. Add to a client – For Claude Desktop, download the provided .mcpb bundle; for Cursor, click the install button; for VS Code, use the UV‑install badge.
5. Query – Use the execute_query tool, e.g. { "sql": "SELECT * FROM orders LIMIT 10" }.

---

Security & Production Tips (from the README)

• Read‑only mode does not block filesystem access; consider Remote MCP for third‑party exposure.
• Use MotherDuck service‑account tokens with read‑scaling and enable SaaS mode to restrict local file access.
• For self‑hosted DuckDB, supply --init-sql with DuckDB security settings (see DuckDB docs).
• Run inside Docker and expose only the needed port.

---

License

MIT – free to use, modify, and redistribute.

---

Bottom line – This repo provides a lightweight bridge that lets modern AI assistants treat DuckDB (or MotherDuck) as a live data source via the standard MCP protocol, enabling real‑time SQL‑driven interactions in IDEs and chat tools.