mcp-server-motherduck 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

mcp_server_motherduck/__init__.py

@@ -26,6 +26,11 @@ def main():
         default=None,
         help="(Default: env var `HOME`) Home directory for DuckDB",
     )
+    parser.add_argument(
+        "--saas-mode",
+        action="store_true",
+        help="Flag for connecting to MotherDuck in SaaS mode",
+    )
     # This is experimental and will change in the future
     parser.add_argument(
         "--result-format",
@@ -45,6 +50,7 @@ def main():
             motherduck_token=args.motherduck_token,
             result_format=args.result_format,
             home_dir=args.home_dir,
+            saas_mode=args.saas_mode,
         )
     )
 

mcp_server_motherduck/server.py

@@ -12,7 +12,7 @@ from mcp.server.models import InitializationOptions
 from .prompt import PROMPT_TEMPLATE
 
 
-SERVER_VERSION = "0.4.1"
+SERVER_VERSION = "0.4.2"
 
 logger = logging.getLogger("mcp_server_motherduck")
 
@@ -24,9 +24,10 @@ class DatabaseClient:
         motherduck_token: str | None = None,
         result_format: Literal["markdown", "duckbox", "text"] = "markdown",
         home_dir: str | None = None,
+        saas_mode: bool = False,
     ):
         self.db_path, self.db_type = self._resolve_db_path_type(
-            db_path, motherduck_token
+            db_path, motherduck_token, saas_mode
         )
         logger.info(f"Database client initialized in `{self.db_type}` mode")
 
@@ -52,14 +53,18 @@ class DatabaseClient:
         return conn
 
     def _resolve_db_path_type(
-        self, db_path: str, motherduck_token: str | None = None
+        self, db_path: str, motherduck_token: str | None = None, saas_mode: bool = False
     ) -> tuple[str, Literal["duckdb", "motherduck"]]:
         """Resolve and validate the database path"""
         # Handle MotherDuck paths
         if db_path.startswith("md:"):
             if motherduck_token:
                 logger.info("Using MotherDuck token to connect to database `md:`")
-                return f"{db_path}?motherduck_token={motherduck_token}", "motherduck"
+                if saas_mode:
+                    logger.info("Connecting to MotherDuck in SaaS mode")
+                    return f"{db_path}?motherduck_token={motherduck_token}&saas_mode=true", "motherduck"
+                else:
+                    return f"{db_path}?motherduck_token={motherduck_token}", "motherduck"
             elif os.getenv("motherduck_token"):
                 logger.info(
                     "Using MotherDuck token from env to connect to database `md:`"
@@ -112,6 +117,7 @@ async def main(
     motherduck_token: str | None = None,
     result_format: Literal["markdown", "duckbox", "text"] = "markdown",
     home_dir: str | None = None,
+    saas_mode: bool = False,
 ):
     logger.info("Starting MotherDuck MCP Server")
     server = Server("mcp-server-motherduck")
@@ -120,6 +126,7 @@ async def main(
         result_format=result_format,
         motherduck_token=motherduck_token,
         home_dir=home_dir,
+        saas_mode=saas_mode,
     )
 
     logger.info("Registering handlers")

{mcp_server_motherduck-0.4.1.dist-info → mcp_server_motherduck-0.4.2.dist-info}/METADATA

@@ -1,26 +1,26 @@
 Metadata-Version: 2.4
 Name: mcp-server-motherduck
-Version: 0.4.1
+Version: 0.4.2
 Summary: A MCP server for MotherDuck and local DuckDB
 Author-email: tdoehmen <till@motherduck.com>
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: duckdb==1.2.1
+Requires-Dist: duckdb==1.2.2
 Requires-Dist: mcp>=1.3.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: tabulate>=0.9.0
 Description-Content-Type: text/markdown
 
-# MotherDuck MCP Server
+# MotherDuck's DuckDB MCP Server
 
-An MCP server implementation that integrates MotherDuck and local DuckDB, providing SQL analytics capabilities to Claude.
+An MCP server implementation that interacts with DuckDB and MotherDuck databases, providing SQL analytics capabilities to AI Assistants and IDEs.
 
 ## Features
 
-- **Hybrid execution**: query data from both cloud-based MotherDuck and local DuckDB
+- **Hybrid execution**: query data from local DuckDB or/and cloud-based MotherDuck databases
 - **Cloud storage integration**: access data stored in Amazon S3 or other cloud storage thanks to MotherDuck's integrations
 - **Data sharing**: create and share databases
-- **SQL analytics**: use DuckDB's SQL dialect to query any size of data directly from Claude
+- **SQL analytics**: use DuckDB's SQL dialect to query any size of data directly from your AI Assistant or IDE
 - **Serverless architecture**: run analytics without needing to configure instances or clusters
 
 ## Components
@@ -35,7 +35,7 @@ The server provides one prompt:
 
 The server offers one tool:
 
-- `query`: Execute a SQL query on the MotherDuck/DuckDB database
+- `query`: Execute a SQL query on the DuckDB or MotherDuck database
   - **Inputs**:
     - `query` (string, required): The SQL query to execute
 
@@ -43,19 +43,49 @@ All interactions with both DuckDB and MotherDuck are done through writing SQL qu
 
 ## Getting Started
 
-### Prerequisites
-
-- A MotherDuck account (sign up at [motherduck.com](https://motherduck.com))
-- A MotherDuck access token
+### General Prerequisites
 - `uv` installed, you can install it using `pip install uv` or `brew install uv`
 
-If you plan to use MotherDuck MCP with Claude Desktop, you will also need Claude Desktop installed.
+If you plan to use the MCP with Claude Desktop or any other MCP comptabile client, the client need to be installed. 
+
+### Prerequisites for DuckDB
+
+- No prerequisites. The MCP server can create an in-memory database on-the-fly 
+- Or connect to an existing local DuckDB database file , or one stored on remote object storage (e.g., AWS S3).
+
+See [Connect to local DuckDB](#connect-to-local-duckdb).
+
+### Prerequisites for MotherDuck
+
+- Sign up for a [MotherDuck account](https://app.motherduck.com/?auth_flow=signup)
+- Generate an access token via the [MotherDuck UI](https://app.motherduck.com/settings/tokens?auth_flow=signup)
+- Store the token securely for use in the configuration
 
-### Setting up your MotherDuck token
+### Usage with Cursor
 
-1. Sign up for a [MotherDuck account](https://app.motherduck.com/?auth_flow=signup)
-2. Generate an access token via the [MotherDuck UI](https://app.motherduck.com/settings/tokens?auth_flow=signup)
-3. Store the token securely for use in the configuration
+1. Install Cursor from [cursor.com/downloads](https://www.cursor.com/downloads) if you haven't already
+
+2. Open Cursor:
+
+- To set it up globally for the first time, go to Settings->MCP and click on "+ Add new global MCP server". 
+- This will open a `mcp.json` file to which you add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
+      ]
+    }
+  }
+}
+```
 
 ### Usage with VS Code
 
@@ -140,7 +170,7 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
         "md:",
         "--motherduck-token",
         "<YOUR_MOTHERDUCK_TOKEN_HERE>"
-      ],
+      ]
     }
   }
 }
@@ -152,9 +182,73 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 - Replace `YOUR_HOME_FOLDER_PATH` with the path to your home directory (needed by DuckDB for file operations). For example, on macOS, it would be `/Users/your_username`
 - The `HOME` environment variable is required for DuckDB to function properly.
 
+## Securing your MCP Server when querying MotherDuck
+
+If the MCP server is exposed to third parties and should only have read access to data, we recommend using a read scaling token and running the MCP server in SaaS mode.
+
+**Read Scaling Tokens** are special access tokens that enable scalable read operations by allowing up to 4 concurrent read replicas, improving performance for multiple end users while *restricting write capabilities*. 
+Refer to the [Read Scaling documentation](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#creating-a-read-scaling-token) to learn how to create a read-scaling token.
+
+**SaaS Mode** in MotherDuck enhances security by restricting it's access to local files, databases, extensions, and configurations, making it ideal for third-party tools that require stricter environment protection. Learn more about it in the [SaaS Mode documentation](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#authentication-using-saas-mode).
+
+**Secure Configuration**
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "<YOUR_READ_SCALING_TOKEN_HERE>",
+        "--saas-mode"
+      ]
+    }
+  }
+}
+```
+
+## Connect to local DuckDB
+
+To connect to a local DuckDB, instead of using the MotherDuck token, specify the path to your local DuckDB database file or use `:memory:` for an in-memory database.
+
+In-memory database:
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        ":memory:"
+      ]
+    }
+  }
+}
+```
+
+Local DuckDB file:
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "/path/to/your/local.db"
+      ]
+    }
+  }
+}
+```
+
 ## Example Queries
 
-Once configured, you can ask Claude to run queries like:
+Once configured, you can e.g. ask Claude to run queries like:
 
 - "Create a new database and table in MotherDuck"
 - "Query data from my local CSV file"
@@ -195,7 +289,7 @@ If you don't specify a database path but have set the `motherduck_token` environ
 
 ## Running in SSE mode
 
-The server could also be run ing SSE mode using `supergateway` by running the following command:
+The server could also be running SSE mode using `supergateway` by running the following command:
 
 ```bash
 npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"
@@ -203,6 +297,30 @@ npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduc
 
 And you can point your clients such as Claude Desktop, Cursor to this endpoint.
 
+## Development configuration
+
+To run the server from a local development environment, use the following configuration:
+
+```json
+ {
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uv",
+      "args": [
+        "--directory", 
+        "/path/to/your/local/mcp-server-motherduck", 
+        "run", 
+        "mcp-server-motherduck", 
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
+      ]
+    }
+  }
+}
+```
+
 ## Troubleshooting
 
 - If you encounter connection issues, verify your MotherDuck token is correct

mcp_server_motherduck-0.4.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_server_motherduck/__init__.py,sha256=dugvMESmREMXUK0u7gRBLOQFFz29RhR7C3DemivAWo4,1826
+mcp_server_motherduck/prompt.py,sha256=P7BrmhVXwDkPeSHQ3f25WMP6lpBpN2BxDzYPOQ3fxX8,56699
+mcp_server_motherduck/server.py,sha256=Z_jDV_CgodFB8JpBYxB8H0iHRHulg-y86GvTC5Szkjc,9446
+mcp_server_motherduck-0.4.2.dist-info/METADATA,sha256=HmnpB0LPxj2s-Nb-Sec_08VLH3K0mLAQZ3pv37xH7zw,11366
+mcp_server_motherduck-0.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_server_motherduck-0.4.2.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
+mcp_server_motherduck-0.4.2.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
+mcp_server_motherduck-0.4.2.dist-info/RECORD,,

mcp_server_motherduck-0.4.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-mcp_server_motherduck/__init__.py,sha256=_HXXeC7-S1nr4oaNEQKt_TKJrdrS_1iWRt557_pX6kI,1642
-mcp_server_motherduck/prompt.py,sha256=P7BrmhVXwDkPeSHQ3f25WMP6lpBpN2BxDzYPOQ3fxX8,56699
-mcp_server_motherduck/server.py,sha256=gu00iJLnTNNxyC5UHA7Xt_7G_5iv32IVCi5RptjcCyk,9085
-mcp_server_motherduck-0.4.1.dist-info/METADATA,sha256=39Ru2YTcZDBCwr4R5T0bBcbs1hYLYlsMRM4csQGk4hg,8006
-mcp_server_motherduck-0.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_server_motherduck-0.4.1.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
-mcp_server_motherduck-0.4.1.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
-mcp_server_motherduck-0.4.1.dist-info/RECORD,,