mcp-server-motherduck 0.3.3__tar.gz → 0.4.0__tar.gz

{mcp_server_motherduck-0.3.3 → mcp_server_motherduck-0.4.0}/.gitignore

@@ -1,5 +1,8 @@
 .DS_Store
 
+# Custom
+.python-version
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

mcp_server_motherduck-0.4.0/PKG-INFO

@@ -0,0 +1,150 @@
+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/README.md

@@ -0,0 +1,137 @@
+# 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.3.3 → mcp_server_motherduck-0.4.0}/pyproject.toml

@@ -1,10 +1,16 @@
 [project]
 name = "mcp-server-motherduck"
-version = "0.3.3"
+version = "0.4.0"
 description = "A MCP server for MotherDuck and local DuckDB"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = [ "mcp>=1.0.0", "duckdb>=1.1.3", "pandas>=2.0.0", "tabulate>=0.9.0" ]
+dependencies = [
+ "mcp>=1.3.0",
+ "duckdb>=1.2.1",
+ "pandas>=2.0.0",
+ "tabulate>=0.9.0",
+]
+
 [[project.authors]]
 name = "tdoehmen"
 email = "till@motherduck.com"

mcp_server_motherduck-0.4.0/src/mcp_server_motherduck/__init__.py

@@ -0,0 +1,53 @@
+from . import server
+import asyncio
+import argparse
+import logging
+
+logger = logging.getLogger("mcp_server_motherduck")
+logging.basicConfig(level=logging.INFO, format="[%(name)s] %(levelname)s - %(message)s")
+
+
+def main():
+    """Main entry point for the package."""
+
+    parser = argparse.ArgumentParser(description="MotherDuck MCP Server")
+    parser.add_argument(
+        "--db-path",
+        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="(Default: `markdown`) Format of the query result",
+        default="markdown",
+        choices=["markdown", "duckbox", "text"],
+    )
+
+    args = parser.parse_args()
+    logger.info("🦆 MotherDuck MCP Server v" + server.SERVER_VERSION)
+    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,
+            motherduck_token=args.motherduck_token,
+            result_format=args.result_format,
+            home_dir=args.home_dir,
+        )
+    )
+
+
+# Optionally expose other important items at package level
+__all__ = ["main", "server"]

{mcp_server_motherduck-0.3.3 → mcp_server_motherduck-0.4.0}/src/mcp_server_motherduck/server.py

@@ -12,7 +12,7 @@ from mcp.server.models import InitializationOptions
 from .prompt import PROMPT_TEMPLATE
 
 
-SERVER_VERSION = "0.3.3"
+SERVER_VERSION = "0.4.0"
 
 logger = logging.getLogger("mcp_server_motherduck")
 
@@ -20,57 +20,79 @@ logger = logging.getLogger("mcp_server_motherduck")
 class DatabaseClient:
     def __init__(
         self,
-        db_path: str = None,
+        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.conn = self._initialize_connection()
+        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")
 
-        return duckdb.connect(
+        conn = duckdb.connect(
             self.db_path,
             config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},
         )
 
+        logger.info(f"✅ Successfully connected to {self.db_type} database")
+
+        return conn
+
     def _resolve_db_path_type(
-        self, db_path: str = 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:
             if self.result_format == "markdown":
                 # Markdown version of the output
-                return self.conn.execute(query).fetchdf().to_markdown()
+                logger.info(
+                    f"🔍 Executing query: {query[:60]}{'...' if len(query) > 60 else ''}"
+                )
+                result = self.conn.execute(query).fetchdf().to_markdown()
+                logger.info("✅ Query executed successfully")
+                return result
             elif self.result_format == "duckbox":
                 # Duckbox version of the output
                 buffer = io.StringIO()
@@ -82,22 +104,23 @@ class DatabaseClient:
                 return str(self.conn.execute(query).fetchall())
 
         except Exception as e:
-            logger.error(f"Database error executing query: {e}")
-            raise ValueError(f"Error executing query: {e}")
-
-    def mcp_config(self) -> 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,
-        }
+            raise ValueError(f"❌ Error executing query: {e}")
 
 
-async def main(db_path: str, result_format: Literal["markdown", "duckbox", "text"] = "markdown"):
-    logger.info(f"Starting MotherDuck MCP Server with DB path: {db_path}")
+async def main(
+    db_path: str,
+    motherduck_token: str | None = None,
+    result_format: Literal["markdown", "duckbox", "text"] = "markdown",
+    home_dir: str | None = None,
+):
+    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")
 
@@ -194,9 +217,15 @@ async def main(db_path: str, result_format: Literal["markdown", "duckbox", "text
         logger.info(f"Calling tool: {name}::{arguments}")
         try:
             if name == "query":
+                if arguments is None:
+                    return [
+                        types.TextContent(type="text", text="Error: No query provided")
+                    ]
                 tool_response = db_client.query(arguments["query"])
                 return [types.TextContent(type="text", text=str(tool_response))]
 
+            return [types.TextContent(type="text", text=f"Unsupported tool: {name}")]
+
         except Exception as e:
             logger.error(f"Error executing tool {name}: {e}")
             raise ValueError(f"Error executing tool {name}: {str(e)}")
@@ -215,3 +244,6 @@ async def main(db_path: str, result_format: Literal["markdown", "duckbox", "text
                 ),
             ),
         )
+
+        # This will only be reached when the server is shutting down
+        logger.info("\n🦆 MotherDuck MCP Server shutting down...")