mcp-server-motherduck 0.4.0__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.0"
+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.2.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: mcp-server-motherduck
+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.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's DuckDB MCP Server
+
+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 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 your AI Assistant or IDE
+- **Serverless architecture**: run analytics without needing to configure instances or clusters
+
+## Components
+
+### Prompts
+
+The server provides one prompt:
+
+- `duckdb-motherduck-initial-prompt`: A prompt to initialize a connection to DuckDB or MotherDuck and start working with it
+
+### Tools
+
+The server offers one tool:
+
+- `query`: Execute a SQL query on the DuckDB or MotherDuck database
+  - **Inputs**:
+    - `query` (string, required): The SQL query to execute
+
+All interactions with both DuckDB and MotherDuck are done through writing SQL queries.
+
+## Getting Started
+
+### General Prerequisites
+- `uv` installed, you can install it using `pip install uv` or `brew install uv`
+
+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
+
+### Usage with Cursor
+
+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
+
+[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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%22md%3A%22%2C%22--motherduck-token%22%2C%22%24%7Binput%3Amotherduck_token%7D%22%5D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22motherduck_token%22%2C%22description%22%3A%22MotherDuck+Token%22%2C%22password%22%3Atrue%7D%5D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%22md%3A%22%2C%22--motherduck-token%22%2C%22%24%7Binput%3Amotherduck_token%7D%22%5D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22motherduck_token%22%2C%22description%22%3A%22MotherDuck+Token%22%2C%22password%22%3Atrue%7D%5D&quality=insiders)
+1. For the quickest installation, click one of the "Install with UV" buttons at the top of this README.
+
+### Manual Installation
+
+Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
+
+```json
+{
+  "mcp": {
+    "inputs": [
+      {
+        "type": "promptString",
+        "id": "motherduck_token",
+        "description": "MotherDuck Token",
+        "password": true
+      }
+    ],
+    "servers": {
+      "motherduck": {
+        "command": "uvx",
+        "args": [
+          "mcp-server-motherduck",
+          "--db-path",
+          "md:",
+          "--motherduck-token",
+          "${input:motherduck_token}"
+        ]
+      }
+    }
+  }
+}
+```
+
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "motherduck_token",
+      "description": "MotherDuck Token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "${input:motherduck_token}"
+      ]
+    }
+  }
+}
+```
+
+### Usage with Claude Desktop
+
+1. Install Claude Desktop from [claude.ai/download](https://claude.ai/download) if you haven't already
+
+2. Open the Claude Desktop configuration file:
+
+- To quickly access it or create it the first time, open the Claude Desktop app, select Settings, and click on the "Developer" tab, finally click on the "Edit Config" button.
+- Add the following configuration to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
+      ]
+    }
+  }
+}
+```
+
+**Important Notes**:
+
+- Replace `YOUR_MOTHERDUCK_TOKEN_HERE` with your actual MotherDuck token
+- 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 e.g. ask Claude to run queries like:
+
+- "Create a new database and table in MotherDuck"
+- "Query data from my local CSV file"
+- "Join data from my local DuckDB database with a table in MotherDuck"
+- "Analyze data stored in Amazon S3"
+
+## Testing
+
+The server is designed to be run by tools like Claude Desktop and Cursor, but you can start it manually for testing purposes. When testing the server manually, you can specify which database to connect to using the `--db-path` parameter:
+
+1. **Default MotherDuck database**:
+
+   - To connect to the default MotherDuck database, you will need to pass the auth token using the `--motherduck-token` parameter.
+
+   ```bash
+   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
+   ```
+
+2. **Specific MotherDuck database**:
+
+   ```bash
+   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
+   ```
+
+3. **Local DuckDB database**:
+
+   ```bash
+   uvx mcp-server-motherduck --db-path /path/to/your/local.db
+   ```
+
+4. **In-memory database**:
+
+   ```bash
+   uvx mcp-server-motherduck --db-path :memory:
+   ```
+
+If you don't specify a database path but have set the `motherduck_token` environment variable, the server will automatically connect to the default MotherDuck database (`md:`).
+
+## Running in SSE mode
+
+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>"
+```
+
+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
+- For local file access problems, ensure the `--home-dir` parameter is set correctly
+- Check that the `uvx` command is available in your PATH
+- If you encounter [`spawn uvx ENOENT`](https://github.com/motherduckdb/mcp-server-motherduck/issues/6) errors, try specifying the full path to `uvx` (output of `which uvx`)
+- In version previous for v0.4.0 we used environment variables, now we use parameters
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

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.0.dist-info/METADATA

@@ -1,150 +0,0 @@
-Metadata-Version: 2.4
-Name: mcp-server-motherduck
-Version: 0.4.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: duckdb>=1.2.1
-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
-
-An MCP server implementation that integrates MotherDuck and local DuckDB, providing SQL analytics capabilities to Claude.
-
-## Features
-
-- **Hybrid execution**: query data from both cloud-based MotherDuck and local DuckDB
-- **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
-- **Serverless architecture**: run analytics without needing to configure instances or clusters
-
-## Components
-
-### Prompts
-
-The server provides one prompt:
-
-- `duckdb-motherduck-initial-prompt`: A prompt to initialize a connection to DuckDB or MotherDuck and start working with it
-
-### Tools
-
-The server offers one tool:
-
-- `query`: Execute a SQL query on the MotherDuck/DuckDB database
-  - **Inputs**:
-    - `query` (string, required): The SQL query to execute
-
-All interactions with both DuckDB and MotherDuck are done through writing SQL queries.
-
-## Getting Started
-
-### Prerequisites
-
-- A MotherDuck account (sign up at [motherduck.com](https://motherduck.com))
-- A MotherDuck access token
-- `uvx` installed, you can install it using `pip install uvx` or `brew install uvx`
-
-If you plan to use MotherDuck MCP with Claude Desktop, you will also need Claude Desktop installed.
-
-### Setting up your MotherDuck token
-
-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
-
-### Usage with Claude Desktop
-
-1. Install Claude Desktop from [claude.ai/download](https://claude.ai/download) if you haven't already
-
-2. Open the Claude Desktop configuration file:
-
-- To quickly access it or create it the first time, open the Claude Desktop app, select Settings, and click on the "Developer" tab, finally click on the "Edit Config" button.
-- Add the following configuration to your `claude_desktop_config.json`:
-
-```json
-"mcpServers": {
-  "mcp-server-motherduck": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-motherduck",
-      "--db-path",
-      "md:",
-      "--motherduck-token",
-      "<YOUR_MOTHERDUCK_TOKEN_HERE>",
-    ],
-  }
-}
-```
-
-**Important Notes**:
-
-- Replace `YOUR_MOTHERDUCK_TOKEN_HERE` with your actual MotherDuck token
-- 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.
-
-## Example Queries
-
-Once configured, you can ask Claude to run queries like:
-
-- "Create a new database and table in MotherDuck"
-- "Query data from my local CSV file"
-- "Join data from my local DuckDB database with a table in MotherDuck"
-- "Analyze data stored in Amazon S3"
-
-## Testing
-
-The server is designed to be run by tools like Claude Desktop and Cursor, but you can start it manually for testing purposes. When testing the server manually, you can specify which database to connect to using the `--db-path` parameter:
-
-1. **Default MotherDuck database**:
-
-   - To connect to the default MotherDuck database, you will need to pass the auth token using the `--motherduck-token` parameter.
-
-   ```bash
-   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
-   ```
-
-2. **Specific MotherDuck database**:
-
-   ```bash
-   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
-   ```
-
-3. **Local DuckDB database**:
-
-   ```bash
-   uvx mcp-server-motherduck --db-path /path/to/your/local.db
-   ```
-
-4. **In-memory database**:
-
-   ```bash
-   uvx mcp-server-motherduck --db-path :memory:
-   ```
-
-If you don't specify a database path but have set the `motherduck_token` environment variable, the server will automatically connect to the default MotherDuck database (`md:`).
-
-## Running in SSE mode
-
-The server could also be run ing 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>"
-```
-
-And you can point your clients such as Claude Desktop, Cursor to this endpoint.
-
-## Troubleshooting
-
-- If you encounter connection issues, verify your MotherDuck token is correct
-- For local file access problems, ensure the `--home-dir` parameter is set correctly
-- Check that the `uvx` command is available in your PATH
-- In version previous for v0.4.0 we used environment variables, now we use parameters
-
-## License
-
-This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

mcp_server_motherduck-0.4.0.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=cS1bLPEnrf3RSHklcAoktGUTxctvhH5DMp2SZ3eA1AM,9085
-mcp_server_motherduck-0.4.0.dist-info/METADATA,sha256=766vAQwLLRwi6fNVoZKI6JpJKhGfEf1oKZWUPfjAwy0,5325
-mcp_server_motherduck-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_server_motherduck-0.4.0.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
-mcp_server_motherduck-0.4.0.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
-mcp_server_motherduck-0.4.0.dist-info/RECORD,,