Initial commit

2026-03-16 10:59:27 +00:00
commit 4ae150f420
3 changed files with 1475 additions and 0 deletions
@@ -0,0 +1,131 @@
+# Snowflake MCP Server
+
+A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for Snowflake, using SSO (browser-based) authentication.
+
+Gives Claude (or any MCP client) the ability to explore your Snowflake account — list databases, schemas, tables, views, describe columns, and run SELECT queries.
+
+## Features
+
+- SSO authentication (opens browser on first connection, then reuses the session)
+- Connection pooling with 30-minute timeout
+- Query caching (5 min TTL)
+- Read-only safety: only SELECT / SHOW / DESCRIBE queries are allowed
+- Async query support for long-running queries
+- Paginated results
+- Multiple output formats (records, columns, split, CSV)
+
+## Quick start with uv
+
+[uv](https://docs.astral.sh/uv/) is the easiest way to run this without managing a virtualenv yourself.
+
+### 1. Install uv (if you don't have it)
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 2. Configure your Snowflake details
+
+Set environment variables (recommended) or edit the defaults at the top of `snowflake_mcp_server.py`.
+
+```bash
+# Required
+export SNOWFLAKE_ACCOUNT="your-account-id"       # e.g. "xy12345.eu-west-1"
+export SNOWFLAKE_USER="your.email@company.com"
+
+# Optional — defaults shown
+export SNOWFLAKE_AUTHENTICATOR="externalbrowser"  # SSO via browser
+export SNOWFLAKE_WAREHOUSE=""                     # uses account default if empty
+export SNOWFLAKE_ROLE=""                          # uses account default if empty
+export SNOWFLAKE_DATABASE=""                      # uses account default if empty
+export SNOWFLAKE_SCHEMA=""                        # uses account default if empty
+```
+
+On Windows (PowerShell):
+```powershell
+$env:SNOWFLAKE_ACCOUNT = "your-account-id"
+$env:SNOWFLAKE_USER = "your.email@company.com"
+```
+
+### 3. Run the server
+
+```bash
+uv run --with snowflake-connector-python --with mcp snowflake_mcp_server.py
+```
+
+Or, if you prefer to create a project first:
+
+```bash
+uv init --no-package
+uv add snowflake-connector-python mcp
+uv run snowflake_mcp_server.py
+```
+
+### 4. Add to Claude Code
+
+**Option A — CLI (easiest):**
+
+```bash
+claude mcp add --transport stdio snowflake \
+  --env SNOWFLAKE_ACCOUNT=your-account-id \
+  --env SNOWFLAKE_USER=your.email@company.com \
+  --env SNOWFLAKE_ROLE=YOUR_ROLE \
+  -- uv run --with snowflake-connector-python --with mcp /absolute/path/to/snowflake_mcp_server.py
+```
+
+**Option B — manual config:**
+
+Add to `.mcp.json` in your project root (shared with team) or `~/.claude.json` (personal):
+
+```json
+{
+  "mcpServers": {
+    "snowflake": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "snowflake-connector-python",
+        "--with", "mcp",
+        "/absolute/path/to/snowflake_mcp_server.py"
+      ],
+      "env": {
+        "SNOWFLAKE_ACCOUNT": "your-account-id",
+        "SNOWFLAKE_USER": "your.email@company.com",
+        "SNOWFLAKE_ROLE": "YOUR_ROLE"
+      }
+    }
+  }
+}
+```
+
+Verify it's registered with `claude mcp list`.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `test_connection` | Verify connectivity and get session info |
+| `list_databases` | List all accessible databases |
+| `list_schemas` | List schemas in a database |
+| `list_tables` | List tables (optionally with row counts) |
+| `list_views` | List views in a schema |
+| `describe_table` | Get column-level schema for a table or view |
+| `describe_query` | Preview output columns without running the full query |
+| `read_data` | Run a SELECT query (up to 50k rows) |
+| `read_data_paginated` | Paginated query results with total count |
+| `read_data_pandas` | Results in records / columns / split / CSV format |
+| `execute_async` | Submit a long-running query asynchronously |
+| `get_query_status` | Check async query progress |
+| `get_async_results` | Fetch results from a completed async query |
+| `list_async_queries` | List all tracked async queries |
+
+## Notes
+
+- The first connection opens your default browser for SSO login. Subsequent calls reuse the session.
+- All queries are validated to be read-only — DML and DDL are blocked.
+- Snowflake object names are case-sensitive when created with quotes. The server will automatically retry with quoted names if the unquoted version fails.