Merge pull request #4 from dynamike/mk-external-browser

Support externalbrowser auth and utilize connection pooling with Snowflake

Author: dynamike

.env.browser.example

@@ -0,0 +1,19 @@
+# Snowflake Connection Parameters - External Browser Authentication Example
+
+# Authentication Type
+SNOWFLAKE_AUTH_TYPE=external_browser
+
+# Connection Parameters
+SNOWFLAKE_ACCOUNT=your_account_id.your_region
+SNOWFLAKE_USER=your_regular_username
+SNOWFLAKE_WAREHOUSE=your_warehouse
+SNOWFLAKE_DATABASE=your_database
+SNOWFLAKE_SCHEMA=your_schema
+SNOWFLAKE_ROLE=your_role
+
+# Note: No private key path is needed for external browser authentication
+# A browser window will open automatically for login when you start the server
+
+# Connection Pooling Settings
+# Time interval in hours between automatic connection refreshes (default: 8)
+SNOWFLAKE_CONN_REFRESH_HOURS=8

.env.example

@@ -0,0 +1,19 @@
+# Snowflake Connection Parameters - Private Key Authentication Example
+
+# Authentication Type
+SNOWFLAKE_AUTH_TYPE=private_key
+
+# Connection Parameters
+SNOWFLAKE_ACCOUNT=your_account_id.your_region
+SNOWFLAKE_USER=your_service_account_username
+SNOWFLAKE_WAREHOUSE=your_warehouse
+SNOWFLAKE_DATABASE=your_database
+SNOWFLAKE_SCHEMA=your_schema
+SNOWFLAKE_ROLE=your_role
+
+# Private Key Authentication Parameters
+SNOWFLAKE_PRIVATE_KEY_PATH=/absolute/path/to/your/private_key.p8
+
+# Connection Pooling Settings
+# Time interval in hours between automatic connection refreshes (default: 8)
+SNOWFLAKE_CONN_REFRESH_HOURS=8

.env.private_key.example

@@ -4,7 +4,12 @@ A Model Context Protocol (MCP) server for performing read-only operations agains
 
 ## Features
 
-- Secure connection to Snowflake using service account authentication with private key
+- Flexible authentication to Snowflake using either:
+  - Service account authentication with private key
+  - External browser authentication for interactive sessions
+- Connection pooling with automatic background refresh to maintain persistent connections
+- Support for querying multiple views and databases in a single session
+- Support for multiple SQL statement types (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH)
 - MCP-compatible handlers for querying Snowflake data
 - Read-only operations with security checks to prevent data modification
 - Support for Python 3.12+
@@ -18,14 +23,16 @@ The server provides the following tools for querying Snowflake:
 - **list_views**: List all views in a specified database and schema
 - **describe_view**: Get detailed information about a specific view including columns and SQL definition
 - **query_view**: Query data from a view with an optional row limit
-- **execute_query**: Execute custom read-only SQL queries (SELECT only) with results formatted as markdown tables
+- **execute_query**: Execute custom read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH) with results formatted as markdown tables
 
 ## Installation
 
 ### Prerequisites
 
 - Python 3.12 or higher
-- A Snowflake account with a configured service account (username + private key)
+- A Snowflake account with either:
+  - A configured service account (username + private key), or
+  - A regular user account for browser-based authentication
 - [uv](https://github.com/astral-sh/uv) package manager (recommended)
 
 ### Steps
@@ -41,16 +48,21 @@ The server provides the following tools for querying Snowflake:
    uv pip install -e .
    ```
 
-3. Create a `.env` file based on `.env.example` with your Snowflake credentials:
+3. Create a `.env` file with your Snowflake credentials:
+
+   Choose one of the provided example files based on your preferred authentication method:
+
+   **For private key authentication**:
+   ```
+   cp .env.private_key.example .env
    ```
-   SNOWFLAKE_ACCOUNT=youraccount.region
-   SNOWFLAKE_USER=your_service_account_username
-   SNOWFLAKE_PRIVATE_KEY_PATH=/absolute/path/to/your/rsa_key.p8
-   SNOWFLAKE_WAREHOUSE=your_warehouse
-   SNOWFLAKE_DATABASE=your_database
-   SNOWFLAKE_SCHEMA=your_schema
-   SNOWFLAKE_ROLE=your_role
+   Then edit the `.env` file to set your Snowflake account details and path to your private key.
+
+   **For external browser authentication**:
+   ```
+   cp .env.browser.example .env
    ```
+   Then edit the `.env` file to set your Snowflake account details.
 
 ## Usage
 
@@ -64,6 +76,8 @@ uv run snowflake-mcp
 
 This will start the stdio-based MCP server, which can be connected to Claude Desktop or any MCP client that supports stdio communication.
 
+When using external browser authentication, a browser window will automatically open prompting you to log in to your Snowflake account.
+
 ### Claude Desktop Integration
 
 1. In Claude Desktop, go to Settings → MCP Servers
@@ -92,13 +106,44 @@ When using with Claude, you can ask questions like:
 - "Show me sample data from the REVENUE_BY_REGION view in the FINANCE database"
 - "Run this SQL query: SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10"
 - "Query the MARKETING database to find the top 5 performing campaigns by conversion rate"
+- "Compare data from views in different databases by querying SALES.CUSTOMER_METRICS and MARKETING.CAMPAIGN_RESULTS"
+
+### Configuration
+
+Connection pooling behavior can be configured through environment variables:
+
+- `SNOWFLAKE_CONN_REFRESH_HOURS`: Time interval in hours between connection refreshes (default: 8)
+
+Example `.env` configuration:
+```
+# Set connection to refresh every 4 hours
+SNOWFLAKE_CONN_REFRESH_HOURS=4
+```
+
+## Authentication Methods
+
+### Private Key Authentication
+
+This method uses a service account and private key for non-interactive authentication, ideal for automated processes.
+
+1. Create a key pair for your Snowflake user following [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth)
+2. Set `SNOWFLAKE_AUTH_TYPE=private_key` in your `.env` file
+3. Provide the path to your private key in `SNOWFLAKE_PRIVATE_KEY_PATH`
+
+### External Browser Authentication
+
+This method opens a browser window for interactive authentication.
+
+1. Set `SNOWFLAKE_AUTH_TYPE=external_browser` in your `.env` file
+2. When you start the server, a browser window will open asking you to log in
+3. After authentication, the session will remain active for the duration specified by your Snowflake account settings
 
 ## Security Considerations
 
 This server:
-- Enforces read-only operations (only SELECT statements are allowed)
+- Enforces read-only operations (only SELECT, SHOW, DESCRIBE, EXPLAIN, and WITH statements are allowed)
 - Automatically adds LIMIT clauses to prevent large result sets
-- Uses service account authentication for secure connections
+- Uses secure authentication methods for connections to Snowflake
 - Validates inputs to prevent SQL injection
 
 ⚠️ **Important**: Keep your `.env` file secure and never commit it to version control. The `.gitignore` file is configured to exclude it.
@@ -123,6 +168,12 @@ ruff check .
 ruff format .
 ```
 
+### Running Tests
+
+```
+pytest
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.