Simple Snowflake MCP server

1# Simple Snowflake MCP server
2[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/YannBrrd/simple_snowflake_mcp)](https://archestra.ai/mcp-catalog/yannbrrd__simple_snowflake_mcp)
3 
4**Enhanced Snowflake MCP Server with comprehensive configuration system and full MCP protocol compliance.**
5 
6A production-ready MCP server that provides seamless Snowflake integration with advanced features including configurable logging, resource subscriptions, and comprehensive error handling. Designed to work seamlessly behind corporate proxies.
7 
8### Tools
9 
10The server exposes comprehensive MCP tools to interact with Snowflake:
11 
12**Core Database Operations:**
13- **execute-snowflake-sql**: Executes a SQL query on Snowflake and returns the result (list of dictionaries)
14- **execute-query**: Executes a SQL query in read-only mode (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH) or not (if `read_only` is false), result in markdown format
15- **query-view**: Queries a view with an optional row limit (markdown result)
16 
17**Discovery and Metadata:**
18- **list-snowflake-warehouses**: Lists available Data Warehouses (DWH) on Snowflake
19- **list-databases**: Lists all accessible Snowflake databases
20- **list-schemas**: Lists all schemas in a specified database
21- **list-tables**: Lists all tables in a database and schema
22- **list-views**: Lists all views in a database and schema
23- **describe-table**: Gives details of a table (columns, types, constraints)
24- **describe-view**: Gives details of a view (columns, SQL)
25 
26**Advanced Operations:**
27- **get-table-sample**: Gets sample data from a table
28- **explain-query**: Explains the execution plan of a SQL query
29- **show-query-history**: Shows recent query history
30- **get-warehouse-status**: Gets current warehouse status and usage
31- **validate-sql**: Validates SQL syntax without execution
32 
33## 🆕 Configuration System (v0.2.0)
34 
35The server now includes a comprehensive YAML-based configuration system that allows you to customize all aspects of the server behavior.
36 
37### Configuration File Structure
38 
39Create a `config.yaml` file in your project root:
40 
41```yaml
42# Logging Configuration
43logging:
44  level: INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
45  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
46  file_logging: false  # Set to true to enable file logging
47  log_file: "mcp_server.log"  # Log file path (when file_logging is true)
48 
49# Server Configuration
50server:
51  name: "simple_snowflake_mcp"
52  version: "0.2.0"
53  description: "Enhanced Snowflake MCP Server with full protocol compliance"
54  connection_timeout: 30
55  read_only: true  # Set to false to allow write operations
56 
57# Snowflake Configuration
58snowflake:
59  read_only: true
60  default_query_limit: 1000
61  max_query_limit: 50000
62 
63# MCP Protocol Settings
64mcp:
65  experimental_features:
66    resource_subscriptions: true  # Enable resource change notifications
67    completion_support: false    # Set to true when MCP version supports it
68  
69  notifications:
70    resources_changed: true
71    tools_changed: true
72  
73  limits:
74    max_prompt_length: 10000
75    max_resource_size: 1048576  # 1MB
76```
77 
78### Using Custom Configuration
79 
80You can specify a custom configuration file using the `CONFIG_FILE` environment variable:
81 
82**Windows:**
83```cmd
84set CONFIG_FILE=config_debug.yaml
85python -m simple_snowflake_mcp
86```
87 
88**Linux/macOS:**
89```bash
90CONFIG_FILE=config_production.yaml python -m simple_snowflake_mcp
91```
92 
93### Configuration Override Priority
94 
95Configuration values are resolved in this order (highest to lowest priority):
961. Environment variables (e.g., `LOG_LEVEL`, `MCP_READ_ONLY`)
972. Custom configuration file (via `CONFIG_FILE`)
983. Default `config.yaml` file
994. Built-in defaults
100 
101## 🚀 Installation Rapide
102 
103### Méthode 1 : Installation avec `uvx` (Recommandé)
104 
105```bash
106# Installation et exécution directe
107uvx simple-snowflake-mcp
108```
109 
110### Méthode 2 : Installation depuis le code source
111 
112```bash
113# Cloner le repo
114git clone https://github.com/YannBrrd/simple_snowflake_mcp
115cd simple_snowflake_mcp
116 
117# Installer avec uv (crée automatiquement un venv)
118uv sync
119 
120# Exécuter
121uv run simple-snowflake-mcp
122```
123 
124### Méthode 3 : Développement
125 
126```bash
127# Installer avec les dépendances de développement
128uv sync --all-extras
129 
130# Lancer les tests
131uv run pytest
132 
133# Linter avec ruff
134uv run ruff check .
135uv run ruff format .
136```
137 
138### Configuration Claude Desktop
139 
140On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
141 
142On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
143 
144<details>
145  <summary>Development/Unpublished Servers Configuration</summary>
146 
147 
148  ```json
149  "mcpServers": {
150    "simple_snowflake_mcp": {
151      "command": "uv",
152      "args": [
153        "--directory",
154        ".", 
155        "run",
156        "simple_snowflake_mcp"
157      ]
158    }
159  }
160  ```
161</details>
162 
163<details>
164  <summary>Published Servers Configuration</summary>
165 
166  ```json
167  "mcpServers": {
168    "simple_snowflake_mcp": {
169      "command": "uvx",
170      "args": [
171        "simple_snowflake_mcp"
172      ]
173    }
174  }
175  ```
176</details>
177 
178## Docker Setup
179 
180### Prerequisites
181 
182- Docker and Docker Compose installed on your system
183- Your Snowflake credentials
184 
185### Quick Start with Docker
186 
1871. **Clone the repository**
188   ```bash
189   git clone <your-repo>
190   cd simple_snowflake_mcp
191   ```
192 
1932. **Set up environment variables**
194   ```bash
195   cp .env.example .env
196   # Edit .env with your Snowflake credentials
197   ```
198 
1993. **Build and run with Docker Compose**
200   ```bash
201   # Build the Docker image
202   docker-compose build
203   
204   # Start the service
205   docker-compose up -d
206   
207   # View logs
208   docker-compose logs -f
209   ```
210 
211### Docker Commands
212 
213Using Docker Compose directly:
214```bash
215# Build the image
216docker-compose build
217 
218# Start in production mode
219docker-compose up -d
220 
221# Start in development mode (with volume mounts for live code changes)
222docker-compose --profile dev up simple-snowflake-mcp-dev -d
223 
224# View logs
225docker-compose logs -f
226 
227# Stop the service
228docker-compose down
229 
230# Clean up (remove containers, images, and volumes)
231docker-compose down --rmi all --volumes --remove-orphans
232```
233 
234Using the provided Makefile (Windows users can use `make` with WSL or install make for Windows):
235```bash
236# See all available commands
237make help
238 
239# Build and start
240make build
241make up
242 
243# Development mode
244make dev-up
245 
246# View logs
247make logs
248 
249# Clean up
250make clean
251```
252 
253### Docker Configuration
254 
255The Docker setup includes:
256 
257- **Dockerfile**: Multi-stage build with Python 3.11 slim base image
258- **docker-compose.yml**: Service definition with environment variable support
259- **.dockerignore**: Optimized build context
260- **Makefile**: Convenient commands for Docker operations
261 
262#### Environment Variables
263 
264All Snowflake configuration can be set via environment variables:
265 
266**Required:**
267- `SNOWFLAKE_USER`: Your Snowflake username
268- `SNOWFLAKE_PASSWORD`: Your Snowflake password
269- `SNOWFLAKE_ACCOUNT`: Your Snowflake account identifier
270 
271**Optional:**
272- `SNOWFLAKE_WAREHOUSE`: Warehouse name
273- `SNOWFLAKE_DATABASE`: Default database
274- `SNOWFLAKE_SCHEMA`: Default schema
275- `MCP_READ_ONLY`: Set to "TRUE" for read-only mode (default: TRUE)
276 
277**Configuration System (v0.2.0):**
278- `CONFIG_FILE`: Path to custom configuration file (default: config.yaml)
279- `LOG_LEVEL`: Override logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
280 
281#### Development Mode
282 
283For development, use the development profile which mounts your source code:
284 
285```bash
286docker-compose --profile dev up simple-snowflake-mcp-dev -d
287```
288 
289This allows you to make changes to the code without rebuilding the Docker image.
290 
291## Développement
292 
293### Installation des dépendances
294 
295```bash
296# Synchroniser toutes les dépendances (prod + dev)
297uv sync --all-extras
298 
299# Mettre à jour les dépendances
300uv lock --upgrade
301 
302# Ajouter une nouvelle dépendance
303uv add <package-name>
304 
305# Ajouter une dépendance de dev
306uv add --dev <package-name>
307```
308 
309### Build et Publication
310 
311```bash
312# Build
313uv build
314 
315# Publier sur PyPI
316uv publish --token $UV_PUBLISH_TOKEN
317```
318 
319### Debugging avec MCP Inspector
320 
321Since MCP servers run over stdio, debugging can be challenging. For the best debugging
322experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
323 
324You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
325 
326```bash
327npx @modelcontextprotocol/inspector uv run simple-snowflake-mcp
328```
329 
330Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
331 
332## New Feature: Snowflake SQL Execution
333 
334The server exposes an MCP tool `execute-snowflake-sql` to execute a SQL query on Snowflake and return the result.
335 
336### Usage
337 
338Call the MCP tool `execute-snowflake-sql` with a `sql` argument containing the SQL query to execute. The result will be returned as a list of dictionaries (one per row).
339 
340Example:
341```json
342{
343  "name": "execute-snowflake-sql",
344  "arguments": { "sql": "SELECT CURRENT_TIMESTAMP;" }
345}
346```
347 
348The result will be returned in the MCP response.
349 
350## Installation et configuration dans VS Code
351 
3521. **Cloner le projet et installer les dépendances**
353   ```sh
354   git clone https://github.com/YannBrrd/simple_snowflake_mcp
355   cd simple_snowflake_mcp
356   
357   # Installer avec uv (crée automatiquement un venv)
358   uv sync --all-extras
359   ```
360 
3612. **Configurer l'accès Snowflake**
362   - Copier `.env.example` vers `.env` et remplir vos credentials :
363     ```env
364     SNOWFLAKE_USER=...
365     SNOWFLAKE_PASSWORD=...
366     SNOWFLAKE_ACCOUNT=...
367     # SNOWFLAKE_WAREHOUSE   Optionnel: Nom du warehouse Snowflake
368     # SNOWFLAKE_DATABASE    Optionnel: Nom de la base par défaut
369     # SNOWFLAKE_SCHEMA      Optionnel: Nom du schéma par défaut
370     # MCP_READ_ONLY=true|false   Optionnel: true/false pour forcer le mode lecture seule
371     ```
372 
3733. **Configurer le serveur (v0.2.0)**
374   - Le serveur créera automatiquement un fichier `config.yaml` par défaut au premier lancement
375   - Personnalisez le logging, les limites et les fonctionnalités MCP en éditant `config.yaml`
376   - Utilisez `CONFIG_FILE=custom_config.yaml` pour spécifier un fichier de configuration différent
377 
3784. **Configurer VS Code pour le debugging MCP**
379   - Le fichier `.vscode/mcp.json` est déjà présent :
380     ```json
381     {
382       "servers": {
383         "simple-snowflake-mcp": {
384           "type": "stdio",
385           "command": "uv",
386           "args": ["run", "simple-snowflake-mcp"]
387         }
388       }
389     }
390     ```
391   - Ouvrir la palette de commandes (Ctrl+Shift+P), taper `MCP: Start Server` et sélectionner `simple-snowflake-mcp`.
392 
3935. **Utilisation**
394   - Les outils MCP exposés vous permettent d'interroger Snowflake (list-databases, list-views, describe-view, query-view, execute-query, etc.).
395   - Pour plus d'exemples, voir la documentation du protocole MCP : https://github.com/modelcontextprotocol/create-python-server
396 
397## Enhanced MCP Features (v0.2.0)
398 
399### Advanced MCP Protocol Support
400 
401This server now implements comprehensive MCP protocol features:
402 
403**🔔 Resource Subscriptions**
404- Real-time notifications when Snowflake resources change
405- Automatic updates for database schema changes
406- Tool availability notifications
407 
408**📋 Enhanced Resource Management**
409- Dynamic resource discovery and listing
410- Detailed resource metadata and descriptions  
411- Support for resource templates and prompts
412 
413**⚡ Performance & Reliability**
414- Configurable query limits and timeouts
415- Comprehensive error handling with detailed error codes
416- Connection pooling and retry mechanisms
417 
418**🔧 Development Features**
419- Multiple output formats (JSON, Markdown, CSV)
420- SQL syntax validation without execution
421- Query execution plan analysis
422- Comprehensive logging with configurable levels
423 
424### MCP Capabilities Advertised
425 
426The server advertises these MCP capabilities:
427- ✅ **Tools**: Full tool execution with comprehensive schemas
428- ✅ **Resources**: Dynamic resource discovery and subscriptions  
429- ✅ **Prompts**: Enhanced prompts with resource integration
430- ✅ **Notifications**: Real-time change notifications
431- 🚧 **Completion**: Ready for future MCP versions (configurable)
432 
433## Supported MCP Functions
434 
435The server exposes comprehensive MCP tools to interact with Snowflake:
436 
437**Core Database Operations:**
438- **execute-snowflake-sql**: Executes a SQL query and returns structured results
439- **execute-query**: Advanced query execution with multiple output formats
440- **query-view**: Optimized view querying with result limiting
441- **validate-sql**: SQL syntax validation without execution
442 
443**Discovery and Metadata:**
444- **list-snowflake-warehouses**: Lists available Data Warehouses with status
445- **list-databases**: Lists all accessible databases with metadata  
446- **list-schemas**: Lists all schemas in a specified database
447- **list-tables**: Lists all tables with column information
448- **list-views**: Lists all views with definitions
449- **describe-table**: Detailed table schema and constraints
450- **describe-view**: View definition and column details
451 
452**Advanced Analytics:**
453- **get-table-sample**: Sample data extraction with configurable limits
454- **explain-query**: Query execution plan analysis
455- **show-query-history**: Recent query history with performance metrics
456- **get-warehouse-status**: Real-time warehouse status and usage
457- **get-account-usage**: Account-level usage statistics
458 
459For detailed usage examples and parameter schemas, see the MCP protocol documentation.
460 
461## 🚀 Getting Started Examples
462 
463### Basic Usage
464```python
465# Execute a simple query
466{
467  "name": "execute-query",
468  "arguments": {
469    "query": "SELECT CURRENT_TIMESTAMP;",
470    "format": "markdown"
471  }
472}
473 
474# List all databases
475{
476  "name": "list-databases",
477  "arguments": {}
478}
479```
480 
481### Advanced Configuration
482```yaml
483# config_production.yaml
484logging:
485  level: WARNING
486  file_logging: true
487  log_file: "/var/log/mcp_server.log"
488 
489server:
490  read_only: false  # Allow write operations
491  
492snowflake:
493  default_query_limit: 5000
494  max_query_limit: 100000
495 
496mcp:
497  experimental_features:
498    resource_subscriptions: true
499```
500 
501### Debugging and Troubleshooting
502 
503**Enable Debug Logging:**
504```bash
505# Method 1: Environment variable
506export LOG_LEVEL=DEBUG
507python -m simple_snowflake_mcp
508 
509# Method 2: Custom config file
510export CONFIG_FILE=config_debug.yaml
511python -m simple_snowflake_mcp
512```
513 
514**Common Issues:**
515- **Connection errors**: Check your Snowflake credentials and network connectivity
516- **Permission errors**: Ensure your user has appropriate Snowflake privileges
517- **Query limits**: Adjust `default_query_limit` in config.yaml for large result sets
518- **MCP compatibility**: Update to latest MCP client version for full feature support
519