mcp-server-motherduck 0.5.1__tar.gz → 0.6.1__tar.gz

{mcp_server_motherduck-0.5.1 → mcp_server_motherduck-0.6.1}/.idea/workspace.xml

@@ -3,16 +3,38 @@
   <component name="AutoImportSettings">
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
+  <component name="CMakeProjectFlavorService">
+    <option name="flavorId" value="CMakePlainProjectFlavor" />
+  </component>
+  <component name="CMakeSettings">
+    <configurations>
+      <configuration PROFILE_NAME="Debug" ENABLED="true" CONFIG_NAME="Debug" />
+    </configurations>
+  </component>
   <component name="ChangeListManager">
     <list default="true" id="8bdee1d4-886c-4093-b4cf-95b120034c9e" name="Changes" comment="">
       <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/mcp_server_motherduck/server.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/mcp_server_motherduck/server.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
     <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
     <option name="LAST_RESOLUTION" value="IGNORE" />
   </component>
+  <component name="ClangdSettings">
+    <option name="formatViaClangd" value="false" />
+  </component>
+  <component name="FlaskConsoleOptions" custom-start-script="import sys&#10;sys.path.extend([WORKING_DIR_AND_PYTHON_PATHS])&#10;from flask.cli import ScriptInfo&#10;locals().update(ScriptInfo(create_app=None).load_app().make_shell_context())&#10;print(&quot;Python %s on %s\nApp: %s [%s]\nInstance: %s&quot; % (sys.version, sys.platform, app.import_name, app.env, app.instance_path))">
+    <envs>
+      <env key="FLASK_APP" value="app" />
+    </envs>
+    <option name="myCustomStartScript" value="import sys&#10;sys.path.extend([WORKING_DIR_AND_PYTHON_PATHS])&#10;from flask.cli import ScriptInfo&#10;locals().update(ScriptInfo(create_app=None).load_app().make_shell_context())&#10;print(&quot;Python %s on %s\nApp: %s [%s]\nInstance: %s&quot; % (sys.version, sys.platform, app.import_name, app.env, app.instance_path))" />
+    <option name="myEnvs">
+      <map>
+        <entry key="FLASK_APP" value="app" />
+      </map>
+    </option>
+  </component>
   <component name="Git.Settings">
     <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
   </component>
@@ -31,7 +53,12 @@
   &quot;keyToString&quot;: {
     &quot;RunOnceActivity.OpenProjectViewOnStart&quot;: &quot;true&quot;,
     &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.cidr.known.project.marker&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.readMode.enableVisualFormatting&quot;: &quot;true&quot;,
     &quot;WebServerToolWindowFactoryState&quot;: &quot;false&quot;,
+    &quot;cf.first.check.clang-format&quot;: &quot;false&quot;,
+    &quot;cidr.known.project.marker&quot;: &quot;true&quot;,
     &quot;git-widget-placeholder&quot;: &quot;main&quot;,
     &quot;last_opened_file_path&quot;: &quot;/Users/doehmen/Documents/motherduck/mcp-server-motherduck&quot;,
     &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
@@ -42,6 +69,7 @@
     &quot;project.structure.last.edited&quot;: &quot;Project&quot;,
     &quot;project.structure.proportion&quot;: &quot;0.0&quot;,
     &quot;project.structure.side.proportion&quot;: &quot;0.0&quot;,
+    &quot;settings.editor.selected.configurable&quot;: &quot;preferences.updates&quot;,
     &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
   }
 }</component>
@@ -57,11 +85,25 @@
       <workItem from="1744787944049" duration="599000" />
       <workItem from="1744896732489" duration="6070000" />
       <workItem from="1747725447463" duration="5949000" />
-      <workItem from="1747924921526" duration="16385000" />
+      <workItem from="1747924921526" duration="17579000" />
+      <workItem from="1749541956173" duration="67000" />
+      <workItem from="1749546948380" duration="272000" />
+      <workItem from="1749547445107" duration="2288000" />
+      <workItem from="1750068892931" duration="1202000" />
+      <workItem from="1750076934923" duration="598000" />
+      <workItem from="1750084124415" duration="194000" />
+      <workItem from="1750084439422" duration="575000" />
+      <workItem from="1750086684829" duration="92000" />
+      <workItem from="1750099676834" duration="5651000" />
+      <workItem from="1750235697329" duration="602000" />
     </task>
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
     <option name="version" value="3" />
   </component>
+  <component name="XSLT-Support.FileAssociations.UIState">
+    <expand />
+    <select />
+  </component>
 </project>

mcp_server_motherduck-0.5.1/README.md → mcp_server_motherduck-0.6.1/PKG-INFO

@@ -1,7 +1,25 @@
+Metadata-Version: 2.4
+Name: mcp-server-motherduck
+Version: 0.6.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: anyio>=4.8.0
+Requires-Dist: click>=8.1.8
+Requires-Dist: duckdb==1.3.1
+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)
@@ -32,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
@@ -81,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)`.
 
@@ -276,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.5.1/PKG-INFO → mcp_server_motherduck-0.6.1/README.md

@@ -1,19 +1,9 @@
-Metadata-Version: 2.4
-Name: mcp-server-motherduck
-Version: 0.5.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.3.0
-Requires-Dist: mcp>=1.3.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.
 
+[![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)
@@ -44,6 +34,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
@@ -93,11 +114,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)`.
 
@@ -288,47 +309,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.5.1 → mcp_server_motherduck-0.6.1}/pyproject.toml

@@ -1,13 +1,17 @@
 [project]
 name = "mcp-server-motherduck"
-version = "0.5.1"
+version = "0.6.1"
 description = "A MCP server for MotherDuck and local DuckDB"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
- "mcp>=1.3.0",
- "duckdb==1.3.0",
+ "duckdb==1.3.1",
  "tabulate>=0.9.0",
+ "click>=8.1.8",
+ "starlette>=0.46.1",
+ "uvicorn>=0.34.0",
+ "anyio>=4.8.0",
+ "mcp>=1.9.4",
 ]
 
 [[project.authors]]

mcp_server_motherduck-0.6.1/src/mcp_server_motherduck/__init__.py

@@ -0,0 +1,193 @@
+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="[motherduck] %(levelname)s - %(message)s"
+)
+
+
+@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."""
+
+    logger.info("🦆 MotherDuck MCP Server v" + SERVER_VERSION)
+    logger.info("Ready to execute SQL queries via DuckDB/MotherDuck")
+
+    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,
+    )
+
+    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"]
+
+if __name__ == "__main__":
+    main()

mcp_server_motherduck-0.6.1/src/mcp_server_motherduck/configs.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+SERVER_VERSION = "0.6.1"
+
+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"},
+    },
+}