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

mcp_server_motherduck/__init__.py

@@ -13,12 +13,23 @@ def main():
     parser = argparse.ArgumentParser(description="MotherDuck MCP Server")
     parser.add_argument(
         "--db-path",
-        help="Path to local DuckDB database file",
+        default="md:",
+        help="(Default: `md:`) Path to local DuckDB database file or MotherDuck database",
+    )
+    parser.add_argument(
+        "--motherduck-token",
+        default=None,
+        help="(Default: env var `motherduck_token`) Access token to use for MotherDuck database connections",
+    )
+    parser.add_argument(
+        "--home-dir",
+        default=None,
+        help="(Default: env var `HOME`) Home directory for DuckDB",
     )
     # This is experimental and will change in the future
     parser.add_argument(
         "--result-format",
-        help="Format of the output",
+        help="(Default: `markdown`) Format of the query result",
         default="markdown",
         choices=["markdown", "duckbox", "text"],
     )
@@ -28,7 +39,14 @@ def main():
     logger.info("Ready to execute SQL queries via DuckDB/MotherDuck")
     logger.info("Waiting for client connection...\n")
 
-    asyncio.run(server.main(db_path=args.db_path, result_format=args.result_format))
+    asyncio.run(
+        server.main(
+            db_path=args.db_path,
+            motherduck_token=args.motherduck_token,
+            result_format=args.result_format,
+            home_dir=args.home_dir,
+        )
+    )
 
 
 # Optionally expose other important items at package level

mcp_server_motherduck/server.py

@@ -12,7 +12,7 @@ from mcp.server.models import InitializationOptions
 from .prompt import PROMPT_TEMPLATE
 
 
-SERVER_VERSION = "0.3.4"
+SERVER_VERSION = "0.4.1"
 
 logger = logging.getLogger("mcp_server_motherduck")
 
@@ -21,18 +21,26 @@ class DatabaseClient:
     def __init__(
         self,
         db_path: str | None = None,
+        motherduck_token: str | None = None,
         result_format: Literal["markdown", "duckbox", "text"] = "markdown",
+        home_dir: str | None = None,
     ):
-        self.db_path, self.db_type = self._resolve_db_path_type(db_path)
+        self.db_path, self.db_type = self._resolve_db_path_type(
+            db_path, motherduck_token
+        )
         logger.info(f"Database client initialized in `{self.db_type}` mode")
 
+        # Set the home directory for DuckDB
+        if home_dir:
+            os.environ["HOME"] = home_dir
+
         self.conn = self._initialize_connection()
         self.result_format = result_format
 
     def _initialize_connection(self) -> duckdb.DuckDBPyConnection:
         """Initialize connection to the MotherDuck or DuckDB database"""
 
-        logger.info(f"🔌 Connecting to {self.db_type} database: {self.db_path}")
+        logger.info(f"🔌 Connecting to {self.db_type} database")
 
         conn = duckdb.connect(
             self.db_path,
@@ -44,32 +52,36 @@ class DatabaseClient:
         return conn
 
     def _resolve_db_path_type(
-        self, db_path: str | None = None
+        self, db_path: str, motherduck_token: str | None = None
     ) -> tuple[str, Literal["duckdb", "motherduck"]]:
         """Resolve and validate the database path"""
-        # Use MotherDuck if token is available and no path specified
-        if db_path is None and os.getenv("motherduck_token"):
-            logger.info("Using MotherDuck token to connect to database `md:`")
-            return "md:", "motherduck"
-
         # Handle MotherDuck paths
-        if db_path and (db_path == "md:" or db_path.startswith("md:")):
-            if not os.getenv("motherduck_token"):
+        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"
+            elif os.getenv("motherduck_token"):
+                logger.info(
+                    "Using MotherDuck token from env to connect to database `md:`"
+                )
+                return (
+                    f"{db_path}?motherduck_token={os.getenv('motherduck_token')}",
+                    "motherduck",
+                )
+            else:
                 raise ValueError(
-                    "Please set the `motherduck_token` environment variable when using `md:` as db_path."
+                    "Please set the `motherduck_token` as an environment variable or pass it as an argument with `--motherduck-token` when using `md:` as db_path."
                 )
-            return db_path, "motherduck"
 
-        # Handle local database paths
-        if db_path:
-            if not os.path.exists(db_path):
-                raise FileNotFoundError(
-                    f"The database path `{db_path}` does not exist."
-                )
+        if db_path == ":memory:":
             return db_path, "duckdb"
 
-        # Default to in-memory database
-        return ":memory:", "duckdb"
+        # Handle local database paths as the last check
+        if not os.path.exists(db_path):
+            raise FileNotFoundError(
+                f"The local database path `{db_path}` does not exist."
+            )
+        return db_path, "duckdb"
 
     def query(self, query: str) -> str:
         try:
@@ -94,21 +106,21 @@ class DatabaseClient:
         except Exception as e:
             raise ValueError(f"❌ Error executing query: {e}")
 
-    def mcp_config(self) -> dict[str, str]:
-        """Used for debugging purposes to show the current MCP config"""
-        return {
-            "current_working_directory": os.getcwd(),
-            "database_type": self.db_type,
-            "database_path": self.db_path,
-        }
-
 
 async def main(
-    db_path: str, result_format: Literal["markdown", "duckbox", "text"] = "markdown"
+    db_path: str,
+    motherduck_token: str | None = None,
+    result_format: Literal["markdown", "duckbox", "text"] = "markdown",
+    home_dir: str | None = None,
 ):
-    logger.info(f"Starting MotherDuck MCP Server with DB path: {db_path}")
+    logger.info("Starting MotherDuck MCP Server")
     server = Server("mcp-server-motherduck")
-    db_client = DatabaseClient(db_path=db_path, result_format=result_format)
+    db_client = DatabaseClient(
+        db_path=db_path,
+        result_format=result_format,
+        motherduck_token=motherduck_token,
+        home_dir=home_dir,
+    )
 
     logger.info("Registering handlers")
 
@@ -235,4 +247,3 @@ async def main(
 
         # This will only be reached when the server is shutting down
         logger.info("\n🦆 MotherDuck MCP Server shutting down...")
-        logger.info(f"Database connection to {db_client.db_path} closed.")

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

@@ -1,14 +1,13 @@
 Metadata-Version: 2.4
 Name: mcp-server-motherduck
-Version: 0.3.4
+Version: 0.4.1
 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.1
 Requires-Dist: mcp>=1.3.0
 Requires-Dist: pandas>=2.0.0
-Requires-Dist: pydantic-settings>=2.8.1
 Requires-Dist: tabulate>=0.9.0
 Description-Content-Type: text/markdown
 
@@ -48,7 +47,7 @@ All interactions with both DuckDB and MotherDuck are done through writing SQL qu
 
 - 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`
+- `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.
 
@@ -58,6 +57,69 @@ If you plan to use MotherDuck MCP with Claude Desktop, you will also need Claude
 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 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
@@ -68,15 +130,17 @@ If you plan to use MotherDuck MCP with Claude Desktop, you will also need Claude
 - Add the following configuration to your `claude_desktop_config.json`:
 
 ```json
-"mcpServers": {
-  "mcp-server-motherduck": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-motherduck"
-    ],
-    "env": {
-      "motherduck_token": "YOUR_MOTHERDUCK_TOKEN_HERE",
-      "HOME": "YOUR_HOME_FOLDER_PATH"
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "md:",
+        "--motherduck-token",
+        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
+      ],
     }
   }
 }
@@ -99,27 +163,20 @@ Once configured, you can ask Claude to run queries like:
 
 ## Testing
 
-The server is designed to be run by tools like Claude Desktop, 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:
+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 export the `motherduck_token` environment variable.
+   - To connect to the default MotherDuck database, you will need to pass the auth token using the `--motherduck-token` parameter.
 
    ```bash
-   export motherduck_token=<your_motherduck_token>
-   uvx mcp-server-motherduck --db-path md:
-   ```
-
-   - Alternatively, you can pass the token directly:
-
-   ```bash
-   motherduck_token=<your_motherduck_token> uvx mcp-server-motherduck --db-path md:
+   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
+   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
    ```
 
 3. **Local DuckDB database**:
@@ -128,10 +185,10 @@ The server is designed to be run by tools like Claude Desktop, but you can start
    uvx mcp-server-motherduck --db-path /path/to/your/local.db
    ```
 
-4. **In-memory database** (default if no path and no token):
+4. **In-memory database**:
 
    ```bash
-   uvx mcp-server-motherduck
+   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:`).
@@ -141,23 +198,18 @@ If you don't specify a database path but have set the `motherduck_token` environ
 The server could also be run ing SSE mode using `supergateway` by running the following command:
 
 ```bash
-motherduck_token=<your_motherduck_token> HOME=<your_home_folder_path> npx -y supergateway --stdio "uvx mcp-server-motherduck"
+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.
 
-### Environment Variables
-
-The server uses the following environment variables:
-
-- `motherduck_token`: Your MotherDuck authentication token
-- `HOME`: Directory used by DuckDB for file operations
-
 ## Troubleshooting
 
 - If you encounter connection issues, verify your MotherDuck token is correct
-- For local file access problems, ensure the `HOME` environment variable is set correctly
+- 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
 

mcp_server_motherduck-0.4.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+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,,

mcp_server_motherduck-0.3.4.dist-info/RECORD

@@ -1,8 +0,0 @@
-mcp_server_motherduck/__init__.py,sha256=fvkO3-wgyUVAdIzy-As4pl3_LYHFMgO9STVTHAyTyKA,1078
-mcp_server_motherduck/prompt.py,sha256=P7BrmhVXwDkPeSHQ3f25WMP6lpBpN2BxDzYPOQ3fxX8,56699
-mcp_server_motherduck/server.py,sha256=N7ySKj43BtMRGE_9HGhWr8_3wGSsjxKD9xIJJv7W4Eg,8841
-mcp_server_motherduck-0.3.4.dist-info/METADATA,sha256=jhdryCCXMVJdKKi0o7E6v9NiJBakx_d9HRECRn21mks,5623
-mcp_server_motherduck-0.3.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_server_motherduck-0.3.4.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
-mcp_server_motherduck-0.3.4.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
-mcp_server_motherduck-0.3.4.dist-info/RECORD,,