mcp-server-motherduck 0.6.4__tar.gz → 0.7.0__tar.gz

mcp_server_motherduck-0.7.0/.github/workflows/publish-mcp.yml

@@ -0,0 +1,74 @@
+name: Publish to PyPI and MCP Registry
+
+on:
+  workflow_dispatch:  # Allows manual triggering from GitHub Actions UI
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for OIDC authentication
+      contents: read
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        id: pypi-publish
+        continue-on-error: true
+        run: |
+          uv publish --token ${{ secrets.PYPI_TOKEN }} 2>&1 | tee publish_output.txt
+          exit_code=${PIPESTATUS[0]}
+          if [ $exit_code -eq 0 ]; then
+            echo "✅ Successfully published to PyPI"
+            echo "pypi_status=success" >> $GITHUB_OUTPUT
+          elif grep -q "already exists" publish_output.txt || grep -q "File already exists" publish_output.txt; then
+            echo "⚠️ Package version already exists on PyPI, skipping..."
+            echo "pypi_status=already_exists" >> $GITHUB_OUTPUT
+            exit 0
+          else
+            echo "❌ Failed to publish to PyPI"
+            echo "pypi_status=failed" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      
+      - name: Setup Node.js (for schema validation)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install MCP Publisher
+        run: |
+          # Clone and build the MCP publisher
+          git clone https://github.com/modelcontextprotocol/registry publisher-repo
+          cd publisher-repo
+          make publisher
+          cp bin/mcp-publisher ../mcp-publisher
+          cd ..
+          chmod +x mcp-publisher
+      
+      - name: Login to MCP Registry
+        run: ./mcp-publisher login github-oidc
+      
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

{mcp_server_motherduck-0.6.4 → mcp_server_motherduck-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-server-motherduck
-Version: 0.6.4
+Version: 0.7.0
 Summary: A MCP server for MotherDuck and local DuckDB
 Author-email: tdoehmen <till@motherduck.com>
 License-File: LICENSE
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 
 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)](cursor://anysphere.cursor-deeplink/mcp/install?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggOm1lbW9yeToiLCJlbnYiOnsibW90aGVyZHVja190b2tlbiI6IiJ9fQ%3D%3D)
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggOm1lbW9yeToiLCJlbnYiOnsibW90aGVyZHVja190b2tlbiI6IiJ9fQ%3D%3D)
 
 ## Resources
 - [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blogpost)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)
@@ -59,7 +59,7 @@ The MCP server supports the following parameters:
 |-----------|------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `--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                                                                                                                                                                                                      |
+| `--db-path` | String | `md:` | Path to local DuckDB database file, MotherDuck database, or S3 URL (e.g., `s3://bucket/path/to/db.duckdb`)                                                                                                                                                     |
 | `--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 or MotherDuck in read-only mode. For DuckDB it uses short-lived connections to enable concurrent access                                                                                                                          |
 | `--home-dir` | String | `None` | Home directory for DuckDB (uses `HOME` env var by default)                                                                                                                                                                                                     |
@@ -354,6 +354,37 @@ modeling data within duckdb and then an MCP client (Windsurf/Cline/Claude/Cursor
 was used for exploring the database. The short lived connections allow each tool
 to run and then release their connection, allowing the next tool to connect.
 
+## Connect to DuckDB on S3
+
+You can connect to DuckDB databases stored on Amazon S3 by providing an S3 URL as the database path. The server will automatically configure the necessary S3 credentials from your environment variables.
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "s3://your-bucket/path/to/database.duckdb"
+      ],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "<your_key>",
+        "AWS_SECRET_ACCESS_KEY": "<your_secret>",
+        "AWS_DEFAULT_REGION": "<your_region>"
+      }
+    }
+  }
+}
+```
+
+
+**Note**: For S3 connections:
+- AWS credentials must be provided via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_DEFAULT_REGION`)
+- The S3 database is attached to an in-memory DuckDB instance
+- The httpfs extension is automatically installed and configured for S3 access
+- Both read and write operations are supported
+
 ## Example Queries
 
 Once configured, you can e.g. ask Claude to run queries like:

{mcp_server_motherduck-0.6.4 → mcp_server_motherduck-0.7.0}/README.md

@@ -2,7 +2,7 @@
 
 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)](cursor://anysphere.cursor-deeplink/mcp/install?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggOm1lbW9yeToiLCJlbnYiOnsibW90aGVyZHVja190b2tlbiI6IiJ9fQ%3D%3D)
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=DuckDB&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItbW90aGVyZHVjayAtLWRiLXBhdGggOm1lbW9yeToiLCJlbnYiOnsibW90aGVyZHVja190b2tlbiI6IiJ9fQ%3D%3D)
 
 ## Resources
 - [Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blogpost)](https://motherduck.com/blog/faster-data-pipelines-with-mcp-duckdb-ai/)
@@ -42,7 +42,7 @@ The MCP server supports the following parameters:
 |-----------|------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `--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                                                                                                                                                                                                      |
+| `--db-path` | String | `md:` | Path to local DuckDB database file, MotherDuck database, or S3 URL (e.g., `s3://bucket/path/to/db.duckdb`)                                                                                                                                                     |
 | `--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 or MotherDuck in read-only mode. For DuckDB it uses short-lived connections to enable concurrent access                                                                                                                          |
 | `--home-dir` | String | `None` | Home directory for DuckDB (uses `HOME` env var by default)                                                                                                                                                                                                     |
@@ -337,6 +337,37 @@ modeling data within duckdb and then an MCP client (Windsurf/Cline/Claude/Cursor
 was used for exploring the database. The short lived connections allow each tool
 to run and then release their connection, allowing the next tool to connect.
 
+## Connect to DuckDB on S3
+
+You can connect to DuckDB databases stored on Amazon S3 by providing an S3 URL as the database path. The server will automatically configure the necessary S3 credentials from your environment variables.
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-motherduck": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-motherduck",
+        "--db-path",
+        "s3://your-bucket/path/to/database.duckdb"
+      ],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "<your_key>",
+        "AWS_SECRET_ACCESS_KEY": "<your_secret>",
+        "AWS_DEFAULT_REGION": "<your_region>"
+      }
+    }
+  }
+}
+```
+
+
+**Note**: For S3 connections:
+- AWS credentials must be provided via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_DEFAULT_REGION`)
+- The S3 database is attached to an in-memory DuckDB instance
+- The httpfs extension is automatically installed and configured for S3 access
+- Both read and write operations are supported
+
 ## Example Queries
 
 Once configured, you can e.g. ask Claude to run queries like:

{mcp_server_motherduck-0.6.4 → mcp_server_motherduck-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-server-motherduck"
-version = "0.6.4"
+version = "0.7.0"
 description = "A MCP server for MotherDuck and local DuckDB"
 readme = "README.md"
 requires-python = ">=3.10"

mcp_server_motherduck-0.7.0/server.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.motherduckdb/mcp-server-motherduck",
+  "description": "Fast analytics and data processing with DuckDB and MotherDuck",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/motherduckdb/mcp-server-motherduck",
+    "source": "github"
+  },
+  "version": "0.7.0",
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "registry_base_url": "https://pypi.org",
+      "identifier": "mcp-server-motherduck",
+      "version": "0.7.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "package_arguments": [
+        {
+          "type": "named",
+          "name": "--transport",
+          "description": "Transport type for MCP server",
+          "default": "stdio",
+          "choices": ["stdio", "sse", "stream"],
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--port",
+          "description": "Port to listen on for sse and stream transport mode",
+          "default": "8000",
+          "format": "number",
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--db-path",
+          "description": "Path to local DuckDB database file or MotherDuck database",
+          "default": "md:",
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--motherduck-token",
+          "description": "Access token to use for MotherDuck database connections",
+          "is_required": false,
+          "is_secret": true
+        },
+        {
+          "type": "named",
+          "name": "--read-only",
+          "description": "Flag for connecting to DuckDB or MotherDuck in read-only mode",
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--home-dir",
+          "description": "Home directory for DuckDB",
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--saas-mode",
+          "description": "Flag for connecting to MotherDuck in SaaS mode (disables filesystem and write permissions for local DuckDB)",
+          "is_required": false
+        },
+        {
+          "type": "named",
+          "name": "--json-response",
+          "description": "Enable JSON responses for HTTP stream (only supported for stream transport)",
+          "is_required": false
+        }
+      ],
+      "environment_variables": [
+        {
+          "name": "motherduck_token",
+          "description": "Access token to use for MotherDuck database connections",
+          "is_required": false,
+          "is_secret": true
+        },
+        {
+          "name": "HOME",
+          "description": "Home directory for DuckDB (used as default if --home-dir not specified)",
+          "is_required": false
+        }
+      ]
+    }
+  ]
+}

{mcp_server_motherduck-0.6.4 → mcp_server_motherduck-0.7.0}/src/mcp_server_motherduck/configs.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-SERVER_VERSION = "0.6.4"
+SERVER_VERSION = "0.7.0"
 
 SERVER_LOCALHOST = "127.0.0.1"
 

{mcp_server_motherduck-0.6.4 → mcp_server_motherduck-0.7.0}/src/mcp_server_motherduck/database.py

@@ -36,6 +36,10 @@ class DatabaseClient:
 
         logger.info(f"🔌 Connecting to {self.db_type} database")
 
+        # S3 databases don't support read-only mode
+        if self.db_type == "s3" and self._read_only:
+            raise ValueError("Read-only mode is not supported for S3 databases")
+
         if self.db_type == "duckdb" and self._read_only:
             # check that we can connect, issue a `select 1` and then close + return None
             try:
@@ -53,6 +57,66 @@ class DatabaseClient:
                 logger.error(f"❌ Read-only check failed: {e}")
                 raise
 
+        # Check if this is an S3 path
+        if self.db_type == "s3":
+            # For S3, we need to create an in-memory connection and attach the S3 database
+            conn = duckdb.connect(':memory:')
+            
+            # Install and load the httpfs extension for S3 support
+            import io
+            from contextlib import redirect_stdout, redirect_stderr
+            
+            null_file = io.StringIO()
+            with redirect_stdout(null_file), redirect_stderr(null_file):
+                try:
+                    conn.execute("INSTALL httpfs;")
+                except:
+                    pass  # Extension might already be installed
+                conn.execute("LOAD httpfs;")
+            
+            # Configure S3 credentials from environment variables using CREATE SECRET
+            aws_access_key = os.environ.get('AWS_ACCESS_KEY_ID')
+            aws_secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY')
+            aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
+            
+            
+            if aws_access_key and aws_secret_key:
+                # Use CREATE SECRET for better credential management
+                conn.execute(f"""
+                    CREATE SECRET IF NOT EXISTS s3_secret (
+                        TYPE S3,
+                        KEY_ID '{aws_access_key}',
+                        SECRET '{aws_secret_key}',
+                        REGION '{aws_region}'
+                    );
+                """)
+            
+            # Attach the S3 database
+            try:
+                # For S3, we always attach as READ_ONLY since S3 storage is typically read-only
+                # Even when not in read_only mode, we attach as READ_ONLY for S3
+                conn.execute(f"ATTACH '{self.db_path}' AS s3db (READ_ONLY);")
+                # Use the attached database
+                conn.execute("USE s3db;")
+                logger.info(f"✅ Successfully connected to {self.db_type} database (attached as read-only)")
+            except Exception as e:
+                logger.error(f"Failed to attach S3 database: {e}")
+                # If the database doesn't exist and we're not in read-only mode, try to create it
+                if "database does not exist" in str(e) and not self._read_only:
+                    logger.info("S3 database doesn't exist, attempting to create it...")
+                    try:
+                        # Create a new database at the S3 location
+                        conn.execute(f"ATTACH '{self.db_path}' AS s3db;")
+                        conn.execute("USE s3db;")
+                        logger.info(f"✅ Created new S3 database at {self.db_path}")
+                    except Exception as create_error:
+                        logger.error(f"Failed to create S3 database: {create_error}")
+                        raise
+                else:
+                    raise
+                
+            return conn
+
         conn = duckdb.connect(
             self.db_path,
             config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},
@@ -65,8 +129,12 @@ class DatabaseClient:
 
     def _resolve_db_path_type(
         self, db_path: str, motherduck_token: str | None = None, saas_mode: bool = False
-    ) -> tuple[str, Literal["duckdb", "motherduck"]]:
+    ) -> tuple[str, Literal["duckdb", "motherduck", "s3"]]:
         """Resolve and validate the database path"""
+        # Handle S3 paths
+        if db_path.startswith("s3://"):
+            return db_path, "s3"
+        
         # Handle MotherDuck paths
         if db_path.startswith("md:"):
             if motherduck_token:
@@ -102,7 +170,7 @@ class DatabaseClient:
 
     def _execute(self, query: str) -> str:
         if self.conn is None:
-            # open short lived readonly connection, run query, close connection, return result
+            # open short lived readonly connection for local DuckDB, run query, close connection, return result
             conn = duckdb.connect(
                 self.db_path,
                 config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},