Simple Snowflake MCP server

Enhanced Snowflake MCP Server with comprehensive configuration system and full MCP protocol compliance.

A 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.

For release details, see CHANGELOG.md.

Tools

The server exposes the following MCP tools to interact with Snowflake:

Database Operations:

• execute-snowflake-sql: Executes a SQL query on Snowflake and returns the result. Supports json (default), markdown, and csv output via the format argument.
• execute-query: Executes a SQL query with server-enforced read-only protection. In read-only mode (the default) only SELECT, SHOW, DESCRIBE, EXPLAIN, and WITH statements (without DML) are allowed. Read-only mode is governed solely by server configuration and cannot be relaxed by the caller. Supports a limit, an offset for paging, and markdown (default)/json/csv output via format. When a result is truncated the response includes the offset for the next page.

Discovery and Metadata:

• get-connection-info: Returns current Snowflake connection information and server status.
• list-snowflake-warehouses: Lists available Data Warehouses (DWH) on Snowflake. Pass include_details: false for names only.
• list-databases: Lists all accessible Snowflake databases. Supports a pattern filter (wildcards) and include_details.
• list-schemas: Lists schemas in a database. Supports a pattern filter (wildcards) and include_details.
• list-tables: Lists tables in a database/schema. Supports a pattern filter (wildcards) and include_details.
• list-views: Lists views in a database/schema. Supports a pattern filter (wildcards) and include_details.
• describe-table: Returns the columns and types of a database/schema/table (works for views too). Supports json (default)/markdown/csv via format.
• query-view: Reads rows from a database/schema/view (or table) by name, with the same server-enforced read-only protection and row limiting as execute-query. Supports a limit, an offset for paging, and markdown (default)/json/csv via format.
• export-schema: Exports hierarchical schema metadata (databases → schemas → tables/views → columns). Supports json (default), yaml, and sql via format, an optional database filter, and opt-in include_data_samples (table rows only, max 3 rows per table).

Notes (in-memory session state):

• add-note: Adds or updates a note (name, content) kept in server memory for the session.
• delete-note: Deletes an existing note by name.
• list-notes: Lists current note names in sorted order.
• get-note: Returns the note payload (name, content) for a given note name.

Prompts

The server also exposes MCP prompts that bundle server context into ready-to-use messages:

• summarize-notes: Summarizes the stored notes. Arguments: style (brief/detailed/executive), format (text/markdown/json).
• analyze-snowflake-schema: Produces a schema-analysis prompt. Arguments: database (optional focus), focus (tables/views/functions/all).
• generate-sql-query: Helps draft a SQL query from a natural-language goal. Arguments: intent (required), complexity (simple/intermediate/advanced).
• troubleshoot-connection: Builds a connection-troubleshooting prompt. Arguments: error_message (optional).

🔒 Security Model

This server executes client-supplied SQL against Snowflake using a single set of credentials. Treat the MCP client as untrusted (an LLM can be prompt-injected) and deploy accordingly.

The real security boundary is a least-privilege Snowflake role, not the server's keyword filter. The built-in read-only check is defense-in-depth only. Always connect with a role scoped to exactly what you need.

Required deployment posture:

1. Use a least-privilege, read-only Snowflake role. For read-only deployments, grant only USAGE/SELECT (and the relevant SHOW/DESCRIBE visibility) — no INSERT/UPDATE/DELETE/DDL/GRANT. If the role cannot write, no bypass of the keyword filter can cause damage.
2. Keep read_only: true (the default). Read-only mode is governed solely by server configuration / the MCP_READ_ONLY environment variable. It is not client-controllable — there is no read_only tool argument.
3. Set a statement timeout and rate limit (see config.yaml) to bound runaway or abusive queries and warehouse-credit consumption.

What the server enforces:

• Read-only mode applies to every SQL-executing tool through a single guard; comments are stripped, multi-statement input and CTE-fronted DML (e.g. WITH ... DELETE) are rejected.
• pattern / database arguments are validated against a strict allow-list before being placed into LIKE clauses; limit is coerced to a bounded integer and applied at the driver, never concatenated into SQL.
• Row-producing reads without an explicit LIMIT are capped at default_query_limit rows (applied at the driver). When a result is capped the response includes an explicit "results were truncated" notice — rows are never dropped silently. Pass a larger limit (up to max_query_limit) or add your own LIMIT clause to retrieve more.
• Snowflake errors are not returned verbatim to the client; a generic message with a reference id is returned and full detail is logged server-side.
• Query text is not logged at INFO (only a length + hash); full SQL is DEBUG-only.

🆕 Configuration System

The server now includes a comprehensive YAML-based configuration system that allows you to customize all aspects of the server behavior.

Configuration File Structure

Create a config.yaml file in your project root:

# Logging Configuration
logging:
  level: INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL (overridable via LOG_LEVEL)
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  file_logging:
    enabled: false        # Set to true to enable file logging
    filename: "logs/server.log"  # Must resolve under repository ./logs/
    max_bytes: 10485760   # Rotate after 10 MB
    backup_count: 5

# Server Configuration
server:
  name: "simple_snowflake_mcp"
  version: "0.4.0"
  description: "Enhanced Snowflake MCP Server with full protocol compliance"
  connection:
    test_on_startup: true
    timeout: 30

# Snowflake Configuration
snowflake:
  # Read-only mode is read from here (and the MCP_READ_ONLY env var), NOT from
  # the server block. Set to false to allow write operations.
  read_only: true
  default_query_limit: 1000
  max_query_limit: 50000
  statement_timeout_seconds: 300
  connection_reuse: true

# Security controls
security:
  rate_limit:
    enabled: true
    max_calls: 60
    window_seconds: 60
  notes:
    max_count: 100
    max_content_length: 10000

# MCP Protocol Settings
mcp:
  experimental_features:
    resource_subscriptions: true  # Enable resource change notifications
    completion_support: false    # Set to true when MCP version supports it
  
  notifications:
    resources_changed: true
    tools_changed: true
    prompts_changed: true

Using Custom Configuration

You can specify a custom configuration file using the CONFIG_FILE environment variable:

Windows:

set CONFIG_FILE=config_debug.yaml
python -m simple_snowflake_mcp

Linux/macOS:

CONFIG_FILE=config_production.yaml python -m simple_snowflake_mcp

Configuration Override Priority

Configuration values are resolved in this order (highest to lowest priority):

1. Environment variables (e.g., LOG_LEVEL, MCP_READ_ONLY)
2. Custom configuration file (via CONFIG_FILE)
3. Default config.yaml file
4. Built-in defaults

🚀 Quick Install

Method 1: Install with uvx (Recommended)

# Install and run directly
uvx simple-snowflake-mcp

Method 2: Install from source

# Clone the repo
git clone https://github.com/YannBrrd/simple_snowflake_mcp
cd simple_snowflake_mcp

# Install with uv (creates a venv automatically)
uv sync

# Run
uv run simple-snowflake-mcp

Method 3: Development

# Install with development dependencies
uv sync --all-extras

# Run the tests
uv run pytest

# Lint with ruff
uv run ruff check .
uv run ruff format .

Configuration Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "simple_snowflake_mcp": {
    "command": "uv",
    "args": [
      "--directory",
      ".", 
      "run",
      "simple_snowflake_mcp"
    ]
  }
}

"mcpServers": {
  "simple_snowflake_mcp": {
    "command": "uvx",
    "args": [
      "simple_snowflake_mcp"
    ]
  }
}

Docker Setup

Prerequisites

• Docker and Docker Compose installed on your system
• Your Snowflake credentials

Quick Start with Docker

1. Clone the repository

   bash

   Copy

   git clone <your-repo>
   cd simple_snowflake_mcp
   

2. Set up environment variables

   bash

   Copy

   cp .env.example .env
   # Edit .env with your Snowflake credentials
   

3. Build and run with Docker Compose

   bash

   Copy

   # Build the Docker image
   docker-compose build
   
   # Start the service
   docker-compose up -d
   
   # View logs
   docker-compose logs -f
   

Docker Commands

Using Docker Compose directly:

# Build the image
docker-compose build