mcp-server-motherduck 0.5__py3-none-any.whl → 0.6.0__py3-none-any.whl

mcp_server_motherduck/__init__.py

@@ -1,66 +1,193 @@
-from . import server
-import asyncio
-import argparse
+import anyio
 import logging
+import click
+from .server import build_application
+from .configs import SERVER_VERSION, SERVER_LOCALHOST, UVICORN_LOGGING_CONFIG
+
+__version__ = SERVER_VERSION
 
 logger = logging.getLogger("mcp_server_motherduck")
-logging.basicConfig(level=logging.INFO, format="[%(name)s] %(levelname)s - %(message)s")
+logging.basicConfig(
+    level=logging.INFO, format="[motherduck] %(levelname)s - %(message)s"
+)
 
 
-def main():
+@click.command()
+@click.option("--port", default=8000, help="Port to listen on for SSE")
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "sse", "stream"]),
+    default="stdio",
+    help="(Default: `stdio`) Transport type",
+)
+@click.option(
+    "--db-path",
+    default="md:",
+    help="(Default: `md:`) Path to local DuckDB database file or MotherDuck database",
+)
+@click.option(
+    "--motherduck-token",
+    default=None,
+    help="(Default: env var `motherduck_token`) Access token to use for MotherDuck database connections",
+)
+@click.option(
+    "--home-dir",
+    default=None,
+    help="(Default: env var `HOME`) Home directory for DuckDB",
+)
+@click.option(
+    "--saas-mode",
+    is_flag=True,
+    help="Flag for connecting to MotherDuck in SaaS mode",
+)
+@click.option(
+    "--read-only",
+    is_flag=True,
+    help="Flag for connecting to DuckDB in read-only mode. Only supported for local DuckDB databases. Also makes use of short lived connections so multiple MCP clients or other systems can remain active (though each operation must be done sequentially).",
+)
+@click.option(
+    "--json-response",
+    is_flag=True,
+    default=False,
+    help="(Default: `False`) Enable JSON responses instead of SSE streams. Only supported for `stream` transport.",
+)
+def main(
+    port,
+    transport,
+    db_path,
+    motherduck_token,
+    home_dir,
+    saas_mode,
+    read_only,
+    json_response,
+):
     """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",
-    )
-    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",
-        help="(Default: `markdown`) Format of the query result",
-        default="markdown",
-        choices=["markdown", "duckbox", "text"],
-    )
+    logger.info("🦆 MotherDuck MCP Server v" + SERVER_VERSION)
+    logger.info("Ready to execute SQL queries via DuckDB/MotherDuck")
 
-    parser.add_argument(
-        "--read-only",
-        action="store_true",
-        help="Flag for connecting to DuckDB in read-only mode. Only supported for local DuckDB databases. Also makes use of short lived connections so multiple MCP clients or other systems can remain active (though each operation must be done sequentially).",
+    app, init_opts = build_application(
+        db_path=db_path,
+        motherduck_token=motherduck_token,
+        home_dir=home_dir,
+        saas_mode=saas_mode,
+        read_only=read_only,
     )
 
-    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,
-            saas_mode=args.saas_mode,
-            read_only=args.read_only,
+    if transport == "sse":
+        from mcp.server.sse import SseServerTransport
+        from starlette.applications import Starlette
+        from starlette.responses import Response
+        from starlette.routing import Mount, Route
+
+        logger.info("MCP server initialized in \033[32msse\033[0m mode")
+
+        sse = SseServerTransport("/messages/")
+
+        async def handle_sse(request):
+            async with sse.connect_sse(
+                request.scope, request.receive, request._send
+            ) as (read_stream, write_stream):
+                await app.run(read_stream, write_stream, init_opts)
+            return Response()
+
+        logger.info(
+            f"🦆 Connect to MotherDuck MCP Server at \033[1m\033[36mhttp://{SERVER_LOCALHOST}:{port}/sse\033[0m"
+        )
+
+        starlette_app = Starlette(
+            debug=True,
+            routes=[
+                Route("/sse", endpoint=handle_sse, methods=["GET"]),
+                Mount("/messages/", app=sse.handle_post_message),
+            ],
+        )
+
+        import uvicorn
+
+        uvicorn.run(
+            starlette_app,
+            host=SERVER_LOCALHOST,
+            port=port,
+            log_config=UVICORN_LOGGING_CONFIG,
+        )
+
+    elif transport == "stream":
+        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+        from collections.abc import AsyncIterator
+        from starlette.applications import Starlette
+        from starlette.routing import Mount
+        from starlette.types import Receive, Scope, Send
+        import contextlib
+
+        logger.info("MCP server initialized in \033[32mhttp-streamable\033[0m mode")
+
+        # Create the session manager with true stateless mode
+        session_manager = StreamableHTTPSessionManager(
+            app=app,
+            event_store=None,
+            json_response=json_response,
+            stateless=True,
+        )
+
+        async def handle_streamable_http(
+            scope: Scope, receive: Receive, send: Send
+        ) -> None:
+            await session_manager.handle_request(scope, receive, send)
+
+        @contextlib.asynccontextmanager
+        async def lifespan(app: Starlette) -> AsyncIterator[None]:
+            """Context manager for session manager."""
+            async with session_manager.run():
+                logger.info("MCP server started with StreamableHTTP session manager")
+                try:
+                    yield
+                finally:
+                    logger.info(
+                        "🦆 MotherDuck MCP Server in \033[32mhttp-streamable\033[0m mode shutting down"
+                    )
+
+        logger.info(
+            f"🦆 Connect to MotherDuck MCP Server at \033[1m\033[36mhttp://{SERVER_LOCALHOST}:{port}/mcp\033[0m"
+        )
+
+        # Create an ASGI application using the transport
+        starlette_app = Starlette(
+            debug=True,
+            routes=[
+                Mount("/mcp", app=handle_streamable_http),
+            ],
+            lifespan=lifespan,
+        )
+
+        import uvicorn
+
+        uvicorn.run(
+            starlette_app,
+            host=SERVER_LOCALHOST,
+            port=port,
+            log_config=UVICORN_LOGGING_CONFIG,
+        )
+
+    else:
+        from mcp.server.stdio import stdio_server
+
+        logger.info("MCP server initialized in \033[32mstdio\033[0m mode")
+        logger.info("Waiting for client connection")
+
+        async def arun():
+            async with stdio_server() as (read_stream, write_stream):
+                await app.run(read_stream, write_stream, init_opts)
+
+        anyio.run(arun)
+        # This will only be reached when the server is shutting down
+        logger.info(
+            "🦆 MotherDuck MCP Server in \033[32mstdio\033[0m mode shutting down"
         )
-    )
 
 
 # Optionally expose other important items at package level
-__all__ = ["main", "server"]
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()

mcp_server_motherduck/configs.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+SERVER_VERSION = "0.6.0"
+
+SERVER_LOCALHOST = "127.0.0.1"
+
+UVICORN_LOGGING_CONFIG: dict[str, Any] = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "()": "uvicorn.logging.DefaultFormatter",
+            "fmt": "[uvicorn]    %(levelname)s - %(message)s",
+            "use_colors": None,
+        },
+    },
+    "handlers": {
+        "default": {
+            "formatter": "default",
+            "class": "logging.StreamHandler",
+            "stream": "ext://sys.stderr",
+        },
+    },
+    "loggers": {
+        "uvicorn": {
+            "handlers": ["default"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "uvicorn.error": {"level": "INFO"},
+    },
+}

mcp_server_motherduck/database.py

@@ -0,0 +1,139 @@
+import os
+import duckdb
+from typing import Literal, Optional
+import io
+from contextlib import redirect_stdout
+from tabulate import tabulate
+import logging
+from .configs import SERVER_VERSION
+
+logger = logging.getLogger("mcp_server_motherduck")
+
+
+class DatabaseClient:
+    def __init__(
+        self,
+        db_path: str | None = None,
+        motherduck_token: str | None = None,
+        home_dir: str | None = None,
+        saas_mode: bool = False,
+        read_only: bool = False,
+    ):
+        self._read_only = read_only
+        self.db_path, self.db_type = self._resolve_db_path_type(
+            db_path, motherduck_token, saas_mode
+        )
+        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()
+
+    def _initialize_connection(self) -> Optional[duckdb.DuckDBPyConnection]:
+        """Initialize connection to the MotherDuck or DuckDB database"""
+
+        logger.info(f"🔌 Connecting to {self.db_type} database")
+
+        if self.db_type == "duckdb" and self._read_only:
+            # check that we can connect, issue a `select 1` and then close + return None
+            try:
+                conn = duckdb.connect(
+                    self.db_path,
+                    config={
+                        "custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"
+                    },
+                    read_only=self._read_only,
+                )
+                conn.execute("SELECT 1")
+                conn.close()
+                return None
+            except Exception as e:
+                logger.error(f"❌ Read-only check failed: {e}")
+                raise
+
+        if self._read_only:
+            raise ValueError(
+                "Read-only mode is only supported for local DuckDB databases. See `saas_mode` for similar functionality with MotherDuck."
+            )
+        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, 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:`")
+                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:`"
+                )
+                return (
+                    f"{db_path}?motherduck_token={os.getenv('motherduck_token')}",
+                    "motherduck",
+                )
+            else:
+                raise ValueError(
+                    "Please set the `motherduck_token` as an environment variable or pass it as an argument with `--motherduck-token` when using `md:` as db_path."
+                )
+
+        if db_path == ":memory:":
+            return db_path, "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 _execute(self, query: str) -> str:
+        if self.conn is None:
+            # open short lived readonly connection, run query, close connection, return result
+            conn = duckdb.connect(
+                self.db_path,
+                config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},
+                read_only=self._read_only,
+            )
+            q = conn.execute(query)
+        else:
+            q = self.conn.execute(query)
+
+        out = tabulate(
+            q.fetchall(),
+            headers=[d[0] + "\n" + d[1] for d in q.description],
+            tablefmt="pretty",
+        )
+
+        if self.conn is None:
+            conn.close()
+
+        return out
+
+    def query(self, query: str) -> str:
+        try:
+            return self._execute(query)
+
+        except Exception as e:
+            raise ValueError(f"❌ Error executing query: {e}")

mcp_server_motherduck/server.py

@@ -1,162 +1,20 @@
-import os
 import logging
-import duckdb
 from pydantic import AnyUrl
-from typing import Literal, Optional
-import io
-from contextlib import redirect_stdout
-import mcp.server.stdio
+from typing import Literal
 import mcp.types as types
 from mcp.server import NotificationOptions, Server
 from mcp.server.models import InitializationOptions
+from .configs import SERVER_VERSION
+from .database import DatabaseClient
 from .prompt import PROMPT_TEMPLATE
 
 
-SERVER_VERSION = "0.5"
-
 logger = logging.getLogger("mcp_server_motherduck")
 
 
-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,
-        saas_mode: bool = False,
-        read_only: bool = False,
-    ):
-        self._read_only = read_only
-        self.db_path, self.db_type = self._resolve_db_path_type(
-            db_path, motherduck_token, saas_mode
-        )
-        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) -> Optional[duckdb.DuckDBPyConnection]:
-        """Initialize connection to the MotherDuck or DuckDB database"""
-
-        logger.info(f"🔌 Connecting to {self.db_type} database")
-
-        if self.db_type == "duckdb" and self._read_only:
-            # check that we can connect, issue a `select 1` and then close + return None
-            try:
-                conn = duckdb.connect(
-                    self.db_path,
-                    config={
-                        "custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"
-                    },
-                    read_only=self._read_only,
-                )
-                conn.execute("SELECT 1")
-                conn.close()
-                return None
-            except Exception as e:
-                logger.error(f"❌ Read-only check failed: {e}")
-                raise
-
-        if self._read_only:
-            raise ValueError(
-                "Read-only mode is only supported for local DuckDB databases. See `saas_mode` for similar functionality with MotherDuck."
-            )
-        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, 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:`")
-                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:`"
-                )
-                return (
-                    f"{db_path}?motherduck_token={os.getenv('motherduck_token')}",
-                    "motherduck",
-                )
-            else:
-                raise ValueError(
-                    "Please set the `motherduck_token` as an environment variable or pass it as an argument with `--motherduck-token` when using `md:` as db_path."
-                )
-
-        if db_path == ":memory:":
-            return db_path, "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 _execute(self, query: str) -> str:
-        if self.conn is None:
-            # open short lived readonly connection, run query, close connection, return result
-            conn = duckdb.connect(
-                self.db_path,
-                config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},
-                read_only=self._read_only,
-            )
-            q = conn.execute(query)
-        else:
-            q = self.conn.execute(query)
-
-        if self.result_format == "markdown":
-            out = q.fetchdf().to_markdown()
-        elif self.result_format == "duckbox":
-            # Duckbox version of the output
-            buffer = io.StringIO()
-            with redirect_stdout(buffer):
-                q.show(max_rows=100, max_col_width=20)
-            out = buffer.getvalue()
-        else:
-            out = str(q.fetchall())
-
-        if self.conn is None:
-            conn.close()
-
-        return out
-
-    def query(self, query: str) -> str:
-        try:
-            return self._execute(query)
-
-        except Exception as e:
-            raise ValueError(f"❌ Error executing query: {e}")
-
-
-async def main(
+def build_application(
     db_path: str,
     motherduck_token: str | None = None,
-    result_format: Literal["markdown", "duckbox", "text"] = "markdown",
     home_dir: str | None = None,
     saas_mode: bool = False,
     read_only: bool = False,
@@ -165,7 +23,6 @@ async def main(
     server = Server("mcp-server-motherduck")
     db_client = DatabaseClient(
         db_path=db_path,
-        result_format=result_format,
         motherduck_token=motherduck_token,
         home_dir=home_dir,
         saas_mode=saas_mode,
@@ -280,20 +137,13 @@ async def main(
             logger.error(f"Error executing tool {name}: {e}")
             raise ValueError(f"Error executing tool {name}: {str(e)}")
 
-    # Run the server using stdin/stdout streams
-    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
-        await server.run(
-            read_stream,
-            write_stream,
-            InitializationOptions(
-                server_name="motherduck",
-                server_version=SERVER_VERSION,
-                capabilities=server.get_capabilities(
-                    notification_options=NotificationOptions(),
-                    experimental_capabilities={},
-                ),
-            ),
-        )
+    initialization_options = InitializationOptions(
+        server_name="motherduck",
+        server_version=SERVER_VERSION,
+        capabilities=server.get_capabilities(
+            notification_options=NotificationOptions(),
+            experimental_capabilities={},
+        ),
+    )
 
-        # This will only be reached when the server is shutting down
-        logger.info("\n🦆 MotherDuck MCP Server shutting down...")
+    return server, initialization_options

{mcp_server_motherduck-0.5.dist-info → mcp_server_motherduck-0.6.0.dist-info}/METADATA

@@ -1,20 +1,25 @@
 Metadata-Version: 2.4
 Name: mcp-server-motherduck
-Version: 0.5
+Version: 0.6.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.2
-Requires-Dist: mcp>=1.3.0
-Requires-Dist: pandas>=2.0.0
+Requires-Dist: anyio>=4.8.0
+Requires-Dist: click>=8.1.8
+Requires-Dist: duckdb==1.3.0
+Requires-Dist: mcp>=1.9.4
+Requires-Dist: starlette>=0.46.1
 Requires-Dist: tabulate>=0.9.0
+Requires-Dist: uvicorn>=0.34.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.
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggbWQ6IiwiZW52Ijp7Im1vdGhlcmR1Y2tfdG9rZW4iOiIifX0%3D)
+
 ## Resources
 - [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blogpost)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)
 - [Faster Data Pipelines development with MCP and DuckDB (YouTube)](https://www.youtube.com/watch?v=yG1mv8ZRxcU)
@@ -45,6 +50,37 @@ The server offers one tool:
 
 All interactions with both DuckDB and MotherDuck are done through writing SQL queries.
 
+## Command Line Parameters
+
+The MCP server supports the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--transport` | Choice | `stdio` | Transport type. Options: `stdio`, `sse`, `stream` |
+| `--port` | Integer | `8000` | Port to listen on for sse and stream transport mode |
+| `--db-path` | String | `md:` | Path to local DuckDB database file or MotherDuck database |
+| `--motherduck-token` | String | `None` | Access token to use for MotherDuck database connections (uses `motherduck_token` env var by default) |
+| `--read-only` | Flag | `False` | Flag for connecting to DuckDB in read-only mode. Only supported for local DuckDB databases. Uses short-lived connections for concurrent access |
+| `--home-dir` | String | `None` | Home directory for DuckDB (uses `HOME` env var by default) |
+| `--saas-mode` | Flag | `False` | Flag for connecting to MotherDuck in SaaS mode |
+| `--json-response` | Flag | `False` | Enable JSON responses for HTTP stream. Only supported for `stream` transport |
+
+### Quick Usage Examples
+
+```bash
+# Connect to local DuckDB file in read-only mode with stream transport mode
+uvx mcp-server-motherduck --transport stream --db-path /path/to/local.db --read-only
+
+# Connect to MotherDuck with token with stream transport mode
+uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN
+
+# Connect to local DuckDB file in read-only mode with stream transport mode
+uvx mcp-server-motherduck --transport stream --db-path /path/to/local.db --read-only
+
+# Connect to MotherDuck in SaaS mode for enhanced security with stream transport mode
+uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN --saas-mode
+```
+
 ## Getting Started
 
 ### General Prerequisites
@@ -94,11 +130,11 @@ See [Connect to local DuckDB](#connect-to-local-duckdb).
 
 ### 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)
+[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-Install_with_UV-0098FF?style=plastic)](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-Install_with_UV-24bfa5?style=plastic&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.
+For the quickest installation, click one of the "Install with UV" buttons at the top.
 
-### Manual Installation
+#### 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)`.
 
@@ -185,7 +221,6 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 **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
@@ -290,47 +325,29 @@ Once configured, you can e.g. ask Claude to run queries like:
 - "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>
-   ```
+## Running in SSE mode
 
-3. **Local DuckDB database**:
+The server can run in SSE mode in two ways:
 
-   ```bash
-   uvx mcp-server-motherduck --db-path /path/to/your/local.db
-   ```
+### Direct SSE mode
 
-4. **In-memory database**:
+Run the server directly in SSE mode using the `--transport sse` flag:
 
-   ```bash
-   uvx mcp-server-motherduck --db-path :memory:
-   ```
+```bash
+uvx mcp-server-motherduck --transport sse --port 8000 --db-path md: --motherduck-token <your_motherduck_token>
+```
 
-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:`).
+This will start the server listening on the specified port (default 8000) and you can point your clients directly to this endpoint.
 
-## Running in SSE mode
+### Using supergateway
 
-The server could also be running SSE mode using `supergateway` by running the following command:
+Alternatively, you can run SSE mode using `supergateway`:
 
 ```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.
+Both methods allow you to point your clients such as Claude Desktop, Cursor to the SSE endpoint.
 
 ## Development configuration
 

mcp_server_motherduck-0.6.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mcp_server_motherduck/__init__.py,sha256=vogjO-bwHYZFut85eeiVmRepamcWHk8bImri_kBKZMU,6026
+mcp_server_motherduck/configs.py,sha256=0owM37f8Vw0Ieqc4eKP7HNrp_W40PcivmlRaaMR4uB0,771
+mcp_server_motherduck/database.py,sha256=RQeVFSL5Uo5hyuysSeJPkz_fCQHijHJYTnBBdPvemvU,4902
+mcp_server_motherduck/prompt.py,sha256=P7BrmhVXwDkPeSHQ3f25WMP6lpBpN2BxDzYPOQ3fxX8,56699
+mcp_server_motherduck/server.py,sha256=U1LM2oQ36gO_pAZuez9HV_u8YDWdER8tQIdDbiXfzx0,5232
+mcp_server_motherduck-0.6.0.dist-info/METADATA,sha256=eJkdX5OBln_0ZGYagtyUiqj5AEIHs1Y4tMdN3uDofAc,13718
+mcp_server_motherduck-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_server_motherduck-0.6.0.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
+mcp_server_motherduck-0.6.0.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
+mcp_server_motherduck-0.6.0.dist-info/RECORD,,

mcp_server_motherduck-0.5.dist-info/RECORD

@@ -1,8 +0,0 @@
-mcp_server_motherduck/__init__.py,sha256=Yd_ron4Fy7mV_p48z0IFNKNbqC7fYfjNnPv4pJ6dRCg,2208
-mcp_server_motherduck/prompt.py,sha256=P7BrmhVXwDkPeSHQ3f25WMP6lpBpN2BxDzYPOQ3fxX8,56699
-mcp_server_motherduck/server.py,sha256=hPZkx1WafvNx8LCLRdq0ftQV_C4qz7x18kqY5ACgZDk,10760
-mcp_server_motherduck-0.5.dist-info/METADATA,sha256=Rg2d2t94aFpd1ArzkAoWY5su_J7n8SoXz9YBY4hGLws,12523
-mcp_server_motherduck-0.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_server_motherduck-0.5.dist-info/entry_points.txt,sha256=dRTgcvWJn40bz0PVuKPylK6w92cFN32lwunZOgo5j4s,69
-mcp_server_motherduck-0.5.dist-info/licenses/LICENSE,sha256=Tj68w9jCiceFKTvZ3jET-008NjhozcQMXpm-fyL9WUI,1067
-mcp_server_motherduck-0.5.dist-info/RECORD,,