{
  "markdown": "<p align=\"center\">\n  <img src=\"src/mcp_server_motherduck/assets/duck_feet_square.png\" alt=\"MotherDuck / DuckDB Local MCP Server\" width=\"120\">\n</p>\n\n<h1 align=\"center\">DuckDB / MotherDuck Local MCP Server</h1>\n\n<p align=\"center\">\n  SQL analytics and data engineering for AI Assistants and IDEs.\n</p>\n\n---\n\nConnect 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.\n\n**Looking for a fully-managed remote MCP server for MotherDuck?** → [Go to the MotherDuck Remote MCP docs](https://motherduck.com/docs/sql-reference/mcp/)\n\n### Remote vs Local MCP\n\n| | **[Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** | **Local MCP** (this repo) |\n|---|---|---|\n| **Hosting** | Hosted by MotherDuck | Runs locally/self-hosted |\n| **Setup** | Zero-setup | Requires local installation |\n| **Access** | Read-write supported | Read-write supported |\n| **Local filesystem** | - | Query across local and remote databases, ingest data from / export data to local filesystem |\n\n> 📝 **Migrating from v0.x?**\n> - **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).\n> - **Default database changed**: `--db-path` default changed from `md:` to `:memory:`. Add `--db-path md:` explicitly for MotherDuck.\n> - **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`.\n\n## Quick Start\n\n**Prerequisites**: Install `uv` via `pip install uv` or `brew install uv`\n\n### Connecting to In-Memory DuckDB (Dev Mode)\n\n```json\n{\n  \"mcpServers\": {\n    \"DuckDB (in-memory, r/w)\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-motherduck\", \"--db-path\", \":memory:\", \"--read-write\", \"--allow-switch-databases\"]\n    }\n  }\n}\n```\n\nFull flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime.\n\n### Connecting to a Local DuckDB File in Read-Only Mode\n\n```json\n{\n  \"mcpServers\": {\n    \"DuckDB (read-only)\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-motherduck\", \"--db-path\", \"/absolute/path/to/your.duckdb\"]\n    }\n  }\n}\n```\n\nConnects 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).\n\n### Connecting to MotherDuck in Read-Write Mode\n\n```json\n{\n  \"mcpServers\": {\n    \"MotherDuck (local, r/w)\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-motherduck\", \"--db-path\", \"md:\", \"--read-write\"],\n      \"env\": {\n        \"motherduck_token\": \"<YOUR_MOTHERDUCK_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\nSee [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.\n\n## Client Setup\n\n| Client | Config Location | One-Click Install |\n|--------|-----------------|-------------------|\n| **Claude Desktop** | Settings → Developer → Edit Config | [.mcpb (MCP Bundle)](https://github.com/motherduckdb/mcp-server-motherduck/releases/latest/download/mcp-server-motherduck.mcpb) |\n| **Claude Code** | Use CLI commands below | - |\n| **Codex CLI** | Use CLI commands below or `~/.codex/config.toml` | - |\n| **Gemini CLI** | Use CLI commands below or `~/.gemini/settings.json` | - |\n| **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) |\n| **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) |\n| **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) |\n\nAny 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.\n\n<details>\n<summary><b>Claude Code CLI commands</b></summary>\n\n**In-Memory DuckDB (Dev Mode):**\n```bash\nclaude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases\n```\n\n**Local DuckDB (Read-Only):**\n```bash\nclaude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb\n```\n\n**MotherDuck (Read-Write):**\n```bash\nclaude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write\n```\n\n</details>\n\n<details>\n<summary><b>Codex CLI commands</b></summary>\n\n**In-Memory DuckDB (Dev Mode):**\n```bash\ncodex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases\n```\n\n**Local DuckDB (Read-Only):**\n```bash\ncodex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb\n```\n\n**MotherDuck (Read-Write):**\n```bash\ncodex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write\n```\n\n</details>\n\n<details>\n<summary><b>Gemini CLI commands</b></summary>\n\n**In-Memory DuckDB (Dev Mode):**\n```bash\ngemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases\n```\n\n**Local DuckDB (Read-Only):**\n```bash\ngemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb\n```\n\n**MotherDuck (Read-Write):**\n```bash\ngemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write\n```\n\n</details>\n\n<details>\n<summary><b>Kiro manual JSON config</b></summary>\n\nAdd 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.\n\n**In-Memory DuckDB (Dev Mode):**\n```json\n{\n  \"mcpServers\": {\n    \"DuckDB (in-memory, r/w)\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-motherduck\", \"--db-path\", \":memory:\", \"--read-write\", \"--allow-switch-databases\"]\n    }\n  }\n}\n```\n\n**MotherDuck (Read-Write):**\n```json\n{\n  \"mcpServers\": {\n    \"MotherDuck (local, r/w)\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-motherduck\", \"--db-path\", \"md:\", \"--read-write\"],\n      \"env\": {\n        \"motherduck_token\": \"<YOUR_MOTHERDUCK_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n## Tools\n\n| Tool | Description | Required Inputs | Optional Inputs |\n|------|-------------|-----------------|-----------------|\n| `execute_query` | Execute SQL query (DuckDB dialect) | `sql` | - |\n| `list_databases` | List all databases (useful for MotherDuck or multiple attached DBs) | - | - |\n| `list_tables` | List tables and views | - | `database`, `schema` |\n| `list_columns` | List columns of a table/view | `table` | `database`, `schema` |\n| `switch_database_connection`* | Switch to different database | `path` | `create_if_not_exists` |\n\n*Requires `--allow-switch-databases` flag\n\nAll tools return JSON. Results are limited to 1024 rows / 50,000 chars by default (configurable via `--max-rows`, `--max-chars`).\n\n## Securing for Production\n\nWhen 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.\n\nFor 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.\n\n**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.\n\n**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.\n\n## Docker\n\nBuild and run the server with Streamable HTTP on port 8000 (defaults to an in-memory DuckDB):\n\n```bash\ndocker build -t mcp-server-motherduck .\ndocker run --rm -p 8000:8000 mcp-server-motherduck\n```\n\nConnect to MotherDuck by passing a token and overriding the command:\n\n```bash\ndocker run --rm -p 8000:8000 \\\n  -e motherduck_token=\"$MOTHERDUCK_TOKEN\" \\\n  mcp-server-motherduck --transport http --db-path md:\n```\n\nThe MCP endpoint is available at `http://localhost:8000/mcp`. CLI flags and env vars from below still apply.\n\n## Command Line Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `--db-path` | `:memory:` | Database path: local file (absolute), `md:` (MotherDuck), or `s3://` URL |\n| `--motherduck-token` | `motherduck_token` env var | MotherDuck access token |\n| `--read-write` | `False` | Enable write access |\n| `--motherduck-saas-mode` | `False` | MotherDuck SaaS mode (restricts local access) |\n| `--allow-switch-databases` | `False` | Enable `switch_database_connection` tool |\n| `--max-rows` | `1024` | Max rows returned |\n| `--max-chars` | `50000` | Max characters returned |\n| `--query-timeout` | `-1` | Query timeout in seconds (-1 = disabled) |\n| `--init-sql` | `None` | SQL to execute on startup |\n| `--motherduck-connection-parameters` | `session_hint=mcp&`<br>`dbinstance_inactivity_ttl=0s` | Additional MotherDuck connection string parameters (`key=value` pairs separated by `&`) |\n| `--ephemeral-connections` | `True` | Use temporary connections for read-only local files |\n| `--transport` | `stdio` | Transport type: `stdio` or `http` |\n| `--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. |\n| `--port` | `8000` | Port for HTTP transport |\n| `--host` | `127.0.0.1` | Host for HTTP transport |\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `motherduck_token` or `MOTHERDUCK_TOKEN` | MotherDuck access token (alternative to `--motherduck-token`) |\n| `HOME` | Used by DuckDB for extensions and config. Override with `--home-dir` if not set. |\n| `AWS_ACCESS_KEY_ID` | AWS access key for S3 database connections |\n| `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3 database connections |\n| `AWS_SESSION_TOKEN` | AWS session token for temporary credentials (IAM roles, SSO, EC2 instance profiles) |\n| `AWS_DEFAULT_REGION` | AWS region for S3 connections |\n| `AWS_ENDPOINT` | AWS endpoint for S3 connections |\n\n## Troubleshooting\n\n- **`spawn uvx ENOENT`**: Specify full path to `uvx` (run `which uvx` to find it)\n- **File locked**: Make sure `--ephemeral-connections` is turned on (default: true) and that you're not connected in read-write mode\n\n## Resources\n\n- [MotherDuck MCP Documentation](https://motherduck.com/docs/sql-reference/mcp/)\n- [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)\n- [Faster Data Pipelines with MCP and DuckDB (YouTube)](https://www.youtube.com/watch?v=yG1mv8ZRxcU)\n\n## Development\n\nTo run from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"Local DuckDB (Dev)\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/mcp-server-motherduck\", \"run\", \"mcp-server-motherduck\", \"--db-path\", \"md:\"],\n      \"env\": {\n        \"motherduck_token\": \"<YOUR_MOTHERDUCK_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n## Release Process\n\n1. Run the `Release New Version` GitHub Action\n2. Enter version in `MAJOR.MINOR.PATCH` format\n3. The workflow bumps version, publishes to PyPI/MCP registry, and creates the GitHub release with MCPB package\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n##\nmcp-name: io.github.motherduckdb/mcp-server-motherduck\n",
  "bytes": 13704,
  "sha": "cdc07c5d812b3beb1e2af54e61f8b9407746002c413334421890f74e0ccc5323",
  "repo_slug": "motherduckdb/mcp-server-motherduck",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_motherduckdb_mcp_server_mother_7b393714/readme"
}