Skip to content
Back to search

mcp-server-motherduck

Local MCP server for DuckDB and MotherDuck

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/motherduckdb/mcp-server-motherduck with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/motherduckdb/mcp-server-motherduck'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/motherduckdb--mcp-server-motherduck/badge.svg)](/listings/motherduckdb--mcp-server-motherduck)

HTML

<a href="/listings/motherduckdb--mcp-server-motherduck"><img src="/api/listings/motherduckdb--mcp-server-motherduck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites**: Install `uv` via `pip install uv` or `brew install uv`

Connecting to In-Memory DuckDB (Dev Mode)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Full flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime.

Connecting to a Local DuckDB File in Read-Only Mode

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

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).

Connecting to MotherDuck in Read-Write Mode

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 301 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  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. <h1 align="center">DuckDB / MotherDuck Local MCP Server</h1>
  5. <p align="center">
  6. SQL analytics and data engineering for AI Assistants and IDEs.
  7. </p>
  8. ---
  9. 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.
  10. **Looking for a fully-managed remote MCP server for MotherDuck?** → [Go to the MotherDuck Remote MCP docs](https://motherduck.com/docs/sql-reference/mcp/)
  11. ### Remote vs Local MCP
  12. | | **[Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** | **Local MCP** (this repo) |
  13. |---|---|---|
  14. | **Hosting** | Hosted by MotherDuck | Runs locally/self-hosted |
  15. | **Setup** | Zero-setup | Requires local installation |
  16. | **Access** | Read-write supported | Read-write supported |
  17. | **Local filesystem** | - | Query across local and remote databases, ingest data from / export data to local filesystem |
  18. ## Quick Start
  19. **Prerequisites**: Install `uv` via `pip install uv` or `brew install uv`
  20. ### Connecting to In-Memory DuckDB (Dev Mode)
  21. ```json
  22. {
  23. "mcpServers": {
  24. "DuckDB (in-memory, r/w)": {
  25. "command": "uvx",
  26. "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
  27. }
  28. }
  29. }
  30. ```
  31. Full flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime.
  32. ### Connecting to a Local DuckDB File in Read-Only Mode
  33. ```json
  34. {
  35. "mcpServers": {
  36. "DuckDB (read-only)": {
  37. "command": "uvx",
  38. "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
  39. }
  40. }
  41. }
  42. ```
  43. 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).
  44. ### Connecting to MotherDuck in Read-Write Mode
  45. ```json
  46. {
  47. "mcpServers": {
  48. "MotherDuck (local, r/w)": {
  49. "command": "uvx",
  50. "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
  51. "env": {
  52. "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
  53. }
  54. }
  55. }
  56. }
  57. ```
  58. 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.
  59. ## Client Setup
  60. | Client | Config Location | One-Click Install |
  61. |--------|-----------------|-------------------|
  62. | **Claude Desktop** | Settings → Developer → Edit Config | [.mcpb (MCP Bundle)](https://github.com/motherduckdb/mcp-server-motherduck/releases/latest/download/mcp-server-motherduck.mcpb) |
  63. | **Claude Code** | Use CLI commands below | - |
  64. | **Codex CLI** | Use CLI commands below or `~/.codex/config.toml` | - |
  65. | **Gemini CLI** | Use CLI commands below or `~/.gemini/settings.json` | - |
  66. | **Cursor** | Settings → MCP → Add new global MCP server | [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor" height="20">](https://cursor.com/en/install-mcp?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggOm1lbW9yeTogLS1yZWFkLXdyaXRlIC0tYWxsb3ctc3dpdGNoLWRhdGFiYXNlcyIsImVudiI6e319) |
  67. | **VS Code** | `Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)" | [![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-server-motherduck&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-motherduck%22%2C%22--db-path%22%2C%22%3Amemory%3A%22%2C%22--read-write%22%2C%22--allow-switch-databases%22%5D%7D) |
  68. | **Kiro** | `~/.kiro/settings/mcp.json` (global) or `.kiro/settings/mcp.json` (project) | [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=DuckDB&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-motherduck%22%2C%22--db-path%22%2C%22%3Amemory%3A%22%2C%22--read-write%22%2C%22--allow-switch-databases%22%5D%7D) |
  69. Any MCP-compatible client can use this server. Add the JSON configuration from [Quick Start](#quick-start) to your client's MCP config file. Consult your client's documentation for the config file location.
  70. <details>
  71. <summary><b>Claude Code CLI commands</b></summary>
  72. **In-Memory DuckDB (Dev Mode):**
  73. ```bash
  74. claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
  75. ```
  76. **Local DuckDB (Read-Only):**
  77. ```bash
  78. claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
  79. ```
  80. **MotherDuck (Read-Write):**
  81. ```bash
  82. claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write
  83. ```
  84. </details>
  85. <details>
  86. <summary><b>Codex CLI commands</b></summary>
  87. **In-Memory DuckDB (Dev Mode):**
  88. ```bash
  89. codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
  90. ```
  91. **Local DuckDB (Read-Only):**
  92. ```bash
  93. codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
  94. ```
  95. **MotherDuck (Read-Write):**
  96. ```bash
  97. codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write
  98. ```
  99. </details>
  100. <details>
  101. <summary><b>Gemini CLI commands</b></summary>
  102. **In-Memory DuckDB (Dev Mode):**
  103. ```bash
  104. gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
  105. ```
  106. **Local DuckDB (Read-Only):**
  107. ```bash
  108. gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
  109. ```
  110. **MotherDuck (Read-Write):**
  111. ```bash
  112. gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write
  113. ```
  114. </details>
  115. <details>
  116. <summary><b>Kiro manual JSON config</b></summary>
  117. Add the following to your Kiro MCP config file (`~/.kiro/settings/mcp.json` for global, or `.kiro/settings/mcp.json` for project-scoped). See the [Kiro MCP documentation](https://kiro.dev/docs/mcp/) for more details.
  118. **In-Memory DuckDB (Dev Mode):**
  119. ```json
  120. {
  121. "mcpServers": {
  122. "DuckDB (in-memory, r/w)": {
  123. "command": "uvx",
  124. "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
  125. }
  126. }
  127. }
  128. ```
  129. **MotherDuck (Read-Write):**
  130. ```json
  131. {
  132. "mcpServers": {
  133. "MotherDuck (local, r/w)": {
  134. "command": "uvx",
  135. "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
  136. "env": {
  137. "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
  138. }
  139. }
  140. }
  141. }
  142. ```
  143. </details>
  144. ## Tools
  145. | Tool | Description | Required Inputs | Optional Inputs |
  146. |------|-------------|-----------------|-----------------|
  147. | `execute_query` | Execute SQL query (DuckDB dialect) | `sql` | - |
  148. | `list_databases` | List all databases (useful for MotherDuck or multiple attached DBs) | - | - |
  149. | `list_tables` | List tables and views | - | `database`, `schema` |
  150. | `list_columns` | List columns of a table/view | `table` | `database`, `schema` |
  151. | `switch_database_connection`* | Switch to different database | `path` | `create_if_not_exists` |
  152. *Requires `--allow-switch-databases` flag
  153. All tools return JSON. Results are limited to 1024 rows / 50,000 chars by default (configurable via `--max-rows`, `--max-chars`).
  154. ## Securing for Production
  155. When giving third parties access to a self-hosted MCP server, **read-only mode alone is not sufficient** — it still allows access to the local filesystem, changing DuckDB settings, and other potentially sensitive operations.
  156. For production deployments with third-party access, we recommend **[MotherDuck Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** — zero-setup, read-write capable, and hosted by MotherDuck.
  157. **Self-hosting MotherDuck MCP:** Fork this repo and customize as needed. Use a **[service account](https://motherduck.com/docs/key-tasks/service-accounts-guide/)** with **[read-scaling tokens](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#creating-a-read-scaling-token)** and enable **[SaaS mode](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#authentication-using-saas-mode)** to restrict local file access.
  158. **Self-hosting DuckDB MCP:** Use `--init-sql` to apply security settings. See the [Securing DuckDB guide](https://duckdb.org/docs/stable/operations_manual/securing_duckdb/overview) for available options.
  159. ## Docker
  160. Build and run the server with Streamable HTTP on port 8000 (defaults to an in-memory DuckDB):
  161. ```bash
  162. docker build -t mcp-server-motherduck .
  163. docker run --rm -p 8000:8000 mcp-server-motherduck
  164. ```
  165. Connect to MotherDuck by passing a token and overriding the command:
  166. ```bash
  167. docker run --rm -p 8000:8000 \
  168. -e motherduck_token="$MOTHERDUCK_TOKEN" \
  169. mcp-server-motherduck --transport http --db-path md:
  170. ```
  171. The MCP endpoint is available at `http://localhost:8000/mcp`. CLI flags and env vars from below still apply.
  172. ## Command Line Parameters
  173. | Parameter | Default | Description |
  174. |-----------|---------|-------------|
  175. | `--db-path` | `:memory:` | Database path: local file (absolute), `md:` (MotherDuck), or `s3://` URL |
  176. | `--motherduck-token` | `motherduck_token` env var | MotherDuck access token |
  177. | `--read-write` | `False` | Enable write access |
  178. | `--motherduck-saas-mode` | `False` | MotherDuck SaaS mode (restricts local access) |
  179. | `--allow-switch-databases` | `False` | Enable `switch_database_connection` tool |
  180. | `--max-rows` | `1024` | Max rows returned |
  181. | `--max-chars` | `50000` | Max characters returned |
  182. | `--query-timeout` | `-1` | Query timeout in seconds (-1 = disabled) |
  183. | `--init-sql` | `None` | SQL to execute on startup |
  184. | `--motherduck-connection-parameters` | `session_hint=mcp&`<br>`dbinstance_inactivity_ttl=0s` | Additional MotherDuck connection string parameters (`key=value` pairs separated by `&`) |
  185. | `--ephemeral-connections` | `True` | Use temporary connections for read-only local files |
  186. | `--transport` | `stdio` | Transport type: `stdio` or `http` |
  187. | `--stateless-http` | `False` | For protocol compatibility only (e.g. with [AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp-protocol-contract.html)). Server still maintains global state via the shared DatabaseClient. |
  188. | `--port` | `8000` | Port for HTTP transport |
  189. | `--host` | `127.0.0.1` | Host for HTTP transport |
  190. ## Environment Variables
  191. | Variable | Description |
  192. |----------|-------------|
  193. | `motherduck_token` or `MOTHERDUCK_TOKEN` | MotherDuck access token (alternative to `--motherduck-token`) |
  194. | `HOME` | Used by DuckDB for extensions and config. Override with `--home-dir` if not set. |
  195. | `AWS_ACCESS_KEY_ID` | AWS access key for S3 database connections |
  196. | `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3 database connections |
  197. | `AWS_SESSION_TOKEN` | AWS session token for temporary credentials (IAM roles, SSO, EC2 instance profiles) |
  198. | `AWS_DEFAULT_REGION` | AWS region for S3 connections |
  199. | `AWS_ENDPOINT` | AWS endpoint for S3 connections |
  200. ## Troubleshooting
  201. - **`spawn uvx ENOENT`**: Specify full path to `uvx` (run `which uvx` to find it)
  202. - **File locked**: Make sure `--ephemeral-connections` is turned on (default: true) and that you're not connected in read-write mode
  203. ## Resources
  204. - [MotherDuck MCP Documentation](https://motherduck.com/docs/sql-reference/mcp/)
  205. - [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)
  206. - [Faster Data Pipelines with MCP and DuckDB (YouTube)](https://www.youtube.com/watch?v=yG1mv8ZRxcU)
  207. ## Development
  208. To run from source:
  209. ```json
  210. {
  211. "mcpServers": {
  212. "Local DuckDB (Dev)": {
  213. "command": "uv",
  214. "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
  215. "env": {
  216. "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
  217. }
  218. }
  219. }
  220. }
  221. ```
  222. ## Release Process
  223. 1. Run the `Release New Version` GitHub Action
  224. 2. Enter version in `MAJOR.MINOR.PATCH` format
  225. 3. The workflow bumps version, publishes to PyPI/MCP registry, and creates the GitHub release with MCPB package
  226. ## License
  227. MIT License - see [LICENSE](LICENSE) file.
  228. ##
  229. mcp-name: io.github.motherduckdb/mcp-server-motherduck

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.