mcp-server-motherduck 0.7.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

mcp_server_motherduck/tools/switch_database_connection.py

@@ -0,0 +1,130 @@
+"""
+Switch database connection tool - Change the primary database connection.
+"""
+
+import os
+from typing import Any
+
+DESCRIPTION = "Switch to a different database connection. The new connection respects the server's read-only/read-write mode."
+
+
+def _is_local_file_path(path: str) -> bool:
+    """Check if path is a local file path (not :memory:, md:, s3://, etc.)."""
+    if path == ":memory:":
+        return False
+    if path.startswith("md:") or path.startswith("motherduck:"):
+        return False
+    if path.startswith("s3://"):
+        return False
+    return True
+
+
+def _validate_path(path: str) -> str | None:
+    """
+    Validate database path.
+
+    Returns None if valid, or an error message if invalid.
+
+    Valid paths:
+    - :memory:
+    - md: or motherduck: paths
+    - s3:// paths
+    - Absolute local file paths
+
+    Invalid:
+    - Relative paths (must use absolute paths for local files)
+    """
+    # Special paths that are always valid
+    if not _is_local_file_path(path):
+        return None
+
+    # Local file paths must be absolute
+    if not os.path.isabs(path):
+        return f"Relative paths are not allowed. Please use an absolute path. Got: {path}"
+
+    return None
+
+
+def switch_database_connection(
+    path: str,
+    db_client: Any,
+    server_read_only: bool = False,
+    create_if_not_exists: bool = False,
+) -> dict[str, Any]:
+    """
+    Switch to a different primary database.
+
+    Args:
+        path: Database path. For local files, must be an absolute path.
+              Also accepts :memory:, md:database_name, or s3:// paths.
+        db_client: DatabaseClient instance (injected by server)
+        server_read_only: Server's global read-only setting (injected by server)
+        create_if_not_exists: If True, create the database file if it doesn't exist.
+                          Only allowed when server is in read-write mode.
+
+    Returns:
+        JSON-serializable dict with result
+    """
+    # Validate path
+    error = _validate_path(path)
+    if error:
+        return {
+            "success": False,
+            "error": error,
+            "errorType": "ValueError",
+        }
+
+    # For local file paths, check if file exists
+    if _is_local_file_path(path):
+        file_exists = os.path.exists(path)
+
+        if not file_exists:
+            if not create_if_not_exists:
+                return {
+                    "success": False,
+                    "error": f"Database file does not exist: {path}. Set create_if_not_exists=True to create a new database.",
+                    "errorType": "FileNotFoundError",
+                }
+
+            if server_read_only:
+                return {
+                    "success": False,
+                    "error": "Cannot create new database file in read-only mode. The server must be started with --read-write to create databases.",
+                    "errorType": "PermissionError",
+                }
+
+    # In-memory databases can't be read-only (DuckDB limitation)
+    if path == ":memory:":
+        effective_read_only = False
+        warning = (
+            "In-memory databases cannot be read-only (DuckDB limitation)"
+            if server_read_only
+            else None
+        )
+    else:
+        effective_read_only = server_read_only
+        warning = None
+
+    try:
+        previous_db = db_client.db_path
+        db_client.switch_database(path, effective_read_only)
+
+        result: dict[str, Any] = {
+            "success": True,
+            "message": f"Switched to database: {path}",
+            "previousDatabase": previous_db,
+            "currentDatabase": path,
+            "readOnly": effective_read_only,
+        }
+
+        if warning:
+            result["warning"] = warning
+
+        return result
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "errorType": type(e).__name__,
+        }

mcp_server_motherduck-1.0.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: mcp-server-motherduck
+Version: 1.0.0
+Summary: A MCP server for MotherDuck and local DuckDB
+Author-email: tdoehmen <till@motherduck.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.8
+Requires-Dist: duckdb==1.4.4
+Requires-Dist: fastmcp<3,>=2.14
+Requires-Dist: pytz>=2025.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="src/mcp_server_motherduck/assets/duck_feet_square.png" alt="MotherDuck / DuckDB Local MCP Server" width="120">
+</p>
+
+<h1 align="center">DuckDB / MotherDuck Local MCP Server</h1>
+
+<p align="center">
+  SQL analytics and data engineering for AI Assistants and IDEs.
+</p>
+
+---
+
+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.
+
+**Looking for a fully-managed remote MCP server for MotherDuck?** → [Go to the MotherDuck Remote MCP docs](https://motherduck.com/docs/sql-reference/mcp/)
+
+### Remote vs Local MCP
+
+| | **[Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** | **Local MCP** (this repo) |
+|---|---|---|
+| **Hosting** | Hosted by MotherDuck | Runs locally/self-hosted |
+| **Setup** | Zero-setup | Requires local installation |
+| **Access** | Read-only | Read-write supported |
+| **Local filesystem** | - | Query across local and remote databases, ingest data from / export data to local filesystem |
+
+> 📝 **Migrating from v0.x?**
+> - **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).
+> - **Default database changed**: `--db-path` default changed from `md:` to `:memory:`. Add `--db-path md:` explicitly for MotherDuck.
+> - **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`.
+
+## Quick Start
+
+**Prerequisites**: Install `uv` via `pip install uv` or `brew install uv`
+
+### Connecting to In-Memory DuckDB (Dev Mode)
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{
+  "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.
+
+## Client Setup
+
+| Client | Config Location | One-Click Install |
+|--------|-----------------|-------------------|
+| **Claude Desktop** | Settings → Developer → Edit Config | [MCPB package](https://github.com/motherduckdb/mcp-server-motherduck/releases) |
+| **Claude Code** | Use CLI commands below | - |
+| **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) |
+| **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) |
+
+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.
+
+<details>
+<summary><b>Claude Code CLI commands</b></summary>
+
+**In-Memory DuckDB (Dev Mode):**
+```bash
+claude mcp add duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
+```
+
+**Local DuckDB (Read-Only):**
+```bash
+claude mcp add duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb
+```
+
+**MotherDuck (Read-Write):**
+```bash
+claude mcp add motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write
+```
+
+</details>
+
+## Tools
+
+| Tool | Description | Required Inputs | Optional Inputs |
+|------|-------------|-----------------|-----------------|
+| `execute_query` | Execute SQL query (DuckDB dialect) | `sql` | - |
+| `list_databases` | List all databases (useful for MotherDuck or multiple attached DBs) | - | - |
+| `list_tables` | List tables and views | - | `database`, `schema` |
+| `list_columns` | List columns of a table/view | `table` | `database`, `schema` |
+| `switch_database_connection`* | Switch to different database | `path` | `create_if_not_exists` |
+
+*Requires `--allow-switch-databases` flag
+
+All tools return JSON. Results are limited to 1024 rows / 50,000 chars by default (configurable via `--max-rows`, `--max-chars`).
+
+## Securing for Production
+
+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.
+
+For production deployments with third-party access, we recommend **[MotherDuck Remote MCP](https://motherduck.com/docs/sql-reference/mcp/)** — zero-setup, read-only, and hosted by MotherDuck.
+
+**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.
+
+**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.
+
+## Command Line Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--db-path` | `:memory:` | Database path: local file (absolute), `md:` (MotherDuck), or `s3://` URL |
+| `--motherduck-token` | `motherduck_token` env var | MotherDuck access token |
+| `--read-write` | `False` | Enable write access |
+| `--motherduck-saas-mode` | `False` | MotherDuck SaaS mode (restricts local access) |
+| `--allow-switch-databases` | `False` | Enable `switch_database_connection` tool |
+| `--max-rows` | `1024` | Max rows returned |
+| `--max-chars` | `50000` | Max characters returned |
+| `--query-timeout` | `-1` | Query timeout in seconds (-1 = disabled) |
+| `--init-sql` | `None` | SQL to execute on startup |
+| `--ephemeral-connections` | `True` | Use temporary connections for read-only local files |
+| `--transport` | `stdio` | Transport type: `stdio` or `http` |
+| `--port` | `8000` | Port for HTTP transport |
+| `--host` | `127.0.0.1` | Host for HTTP transport |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `motherduck_token` or `MOTHERDUCK_TOKEN` | MotherDuck access token (alternative to `--motherduck-token`) |
+| `HOME` | Used by DuckDB for extensions and config. Override with `--home-dir` if not set. |
+| `AWS_ACCESS_KEY_ID` | AWS access key for S3 database connections |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3 database connections |
+| `AWS_SESSION_TOKEN` | AWS session token for temporary credentials (IAM roles, SSO, EC2 instance profiles) |
+| `AWS_DEFAULT_REGION` | AWS region for S3 connections |
+
+## Troubleshooting
+
+- **`spawn uvx ENOENT`**: Specify full path to `uvx` (run `which uvx` to find it)
+- **File locked**: Make sure `--ephemeral-connections` is turned on (default: true) and that you're not connected in read-write mode
+
+## Resources
+
+- [MotherDuck MCP Documentation](https://motherduck.com/docs/sql-reference/mcp/)
+- [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)
+- [Faster Data Pipelines with MCP and DuckDB (YouTube)](https://www.youtube.com/watch?v=yG1mv8ZRxcU)
+
+## Development
+
+To run from source:
+
+```json
+{
+  "mcpServers": {
+    "Local DuckDB (Dev)": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
+      "env": {
+        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+## Release Process
+
+1. Run the `Release New Version` GitHub Action
+2. Enter version in `MAJOR.MINOR.PATCH` format
+3. The workflow bumps version, publishes to PyPI/MCP registry, and creates the GitHub release with MCPB package
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+##
+mcp-name: io.github.motherduckdb/mcp-server-motherduck

mcp_server_motherduck-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcp_server_motherduck/__init__.py,sha256=Kn6Bla9XiEOUs27xC2eGF6AqbqW2kl1U4NIfNcxNZ8I,8778
+mcp_server_motherduck/configs.py,sha256=7dp4moLZ7hskacbC2ric7-kZgmz3X7bFTm4Hte07Erc,771
+mcp_server_motherduck/database.py,sha256=vaFzGiQckwLnwSICAItHz0M7HUkE0rloxTIJ2Fw8ik0,17436
+mcp_server_motherduck/instructions.py,sha256=U5PviYJ7bTxpr6geeqrdYnNgNQhDuQinL6tD-g9w4jk,6557
+mcp_server_motherduck/server.py,sha256=DCTdhRqKqW8gFWtKzgyluTFhBL-AeI8APvco8MnDHSo,8719
+mcp_server_motherduck/assets/duck_feet_square.png,sha256=P3j0ERFMeSyy67HA2wHxuDLNGhRcMd5LngLibtZ9TzA,6193
+mcp_server_motherduck/tools/__init__.py,sha256=95JNMlxICn8w5O-mjMsqP7vVWsu45LYTn0AUtjR7W2A,466
+mcp_server_motherduck/tools/execute_query.py,sha256=dcHECyZpr-85Ic8E-pfMM9oqfCF_ehW0OKRXkcyOEkE,563
+mcp_server_motherduck/tools/list_columns.py,sha256=PLhhOddCaBwWEX-bX3Hg3heEHkLz8mRHhz4LIQwwYjo,2855
+mcp_server_motherduck/tools/list_databases.py,sha256=xE-swUgttvllz81Jf_Ngdr_qJ_sBTd0OOaaObPhXVZ0,1665
+mcp_server_motherduck/tools/list_tables.py,sha256=9rd4-tHXEOq3ezDdxpxPr9JpPTSft8enIj0Qc33oSMY,2540
+mcp_server_motherduck/tools/switch_database_connection.py,sha256=Yuaj-oXZIfguNMjdKsGYagOlXooKe8B9H4U1G83HfIs,3880
+mcp_server_motherduck-1.0.0.dist-info/METADATA,sha256=FosKIyVTwLXfk90KzTXJTPByKRlsg0gHblDx42QQv9c,10763
+mcp_server_motherduck-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_server_motherduck-1.0.0.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
+mcp_server_motherduck-1.0.0.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
+mcp_server_motherduck-1.0.0.dist-info/RECORD,,

{mcp_server_motherduck-0.7.2.dist-info → mcp_server_motherduck-1.0.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any