MCP Snowflake Server

A Model Context Protocol (MCP) server that connects to Snowflake databases and executes SQL queries.

Features

• List Schemas: Retrieve a list of schemas from a specified database
• List Tables: Retrieve a list of tables from a specified database and schema
• List Views: Retrieve a list of views from a specified database and schema
• Describe Table: Retrieve detailed structure information for a specified table
• Execute Query: Execute read-only SQL queries and return results
• Sample Table Data: Retrieve sample data from a specified table using Snowflake's SAMPLE ROW clause
• Analyze Table Statistics: Generate comprehensive statistical analysis for table columns using Snowflake's high-performance approximation functions (supports numeric, string, date, and boolean columns)

Installation

Prerequisites

• Python 3.13 or higher
• uv (Python package manager)
• Access to a Snowflake account

Setup

1. Clone the repository:

git clone <repository-url>
cd mcp-snowflake

2. Install using uv:

uv tool install -e .

Configuration

Using Configuration File (Recommended)

1. Copy the configuration file sample:

cp .mcp_snowflake.toml.example .mcp_snowflake.toml

2. Edit .mcp_snowflake.toml to configure your Snowflake connection:

[snowflake]
account = "your-account.region"
user = "your-username"
password = "your-password"
warehouse = "your-warehouse"  # Optional
role = "your-role"  # Optional
authenticator = "SNOWFLAKE"  # "SNOWFLAKE" or "externalbrowser"

[tools]
# Enable/disable specific tools (all enabled by default)
analyze_table_statistics = true  # Optional
describe_table = true  # Optional
execute_query = true  # Optional
list_schemas = true  # Optional
list_tables = true  # Optional
list_views = true  # Optional
sample_table_data = true  # Optional

Using Environment Variables

Set the following environment variables:

Required

• SNOWFLAKE__ACCOUNT: Snowflake account identifier
• SNOWFLAKE__USER: Username
• SNOWFLAKE__PASSWORD: Password

Optional

• SNOWFLAKE__WAREHOUSE: Default warehouse
• SNOWFLAKE__ROLE: Default role
• SNOWFLAKE__AUTHENTICATOR: Authentication method ("SNOWFLAKE" or "externalbrowser")

Tool Configuration (Optional)

• TOOLS__ANALYZE_TABLE_STATISTICS: Enable/disable analyze_table_statistics tool ("true" or "false", default: "true")
• TOOLS__DESCRIBE_TABLE: Enable/disable describe_table tool ("true" or "false", default: "true")
• TOOLS__EXECUTE_QUERY: Enable/disable execute_query tool ("true" or "false", default: "true")
• TOOLS__LIST_SCHEMAS: Enable/disable list_schemas tool ("true" or "false", default: "true")
• TOOLS__LIST_TABLES: Enable/disable list_tables tool ("true" or "false", default: "true")
• TOOLS__LIST_VIEWS: Enable/disable list_views tool ("true" or "false", default: "true")
• TOOLS__SAMPLE_TABLE_DATA: Enable/disable sample_table_data tool ("true" or "false", default: "true")

Example:

export SNOWFLAKE__ACCOUNT="your-account.region"
export SNOWFLAKE__USER="your-username"
export SNOWFLAKE__PASSWORD="your-password"
export SNOWFLAKE__WAREHOUSE="your-warehouse"
export SNOWFLAKE__ROLE="your-role"
export SNOWFLAKE__AUTHENTICATOR="SNOWFLAKE"

For PowerShell (Windows):

$env:SNOWFLAKE__ACCOUNT="your-account.region"
$env:SNOWFLAKE__USER="your-username"
$env:SNOWFLAKE__PASSWORD="your-password"
$env:SNOWFLAKE__WAREHOUSE="your-warehouse"
$env:SNOWFLAKE__ROLE="your-role"
$env:SNOWFLAKE__AUTHENTICATOR="SNOWFLAKE"

# Tool configuration (optional)
$env:TOOLS__EXECUTE_QUERY="false"  # Disable execute_query tool
$env:TOOLS__ANALYZE_TABLE_STATISTICS="false"  # Disable analyze_table_statistics tool

Note

Environment variables are separated by double underscores (__).

Usage

Start the MCP server:

uvx mcp-snowflake --config {your-config-path}

Available Tools

Tool List

• list_schemas - Retrieve a list of schemas from a specified database
• list_tables - Retrieve a list of tables from a specified database and schema
• list_views - Retrieve a list of views from a specified database and schema
• describe_table - Retrieve detailed structure information for a specified table
• execute_query - Execute read-only SQL queries and return structured results
• sample_table_data - Retrieve sample data from a specified table
• analyze_table_statistics - Generate comprehensive statistical analysis for table columns

list_schemas

Retrieve a list of schemas from a specified database.

Parameters:

• database (string, required): Database name to retrieve schemas from

Example:

{
  "name": "list_schemas",
  "arguments": {
    "database": "MY_DATABASE"
  }
}

list_tables

Retrieve a list of tables from a specified database and schema.

Parameters:

• database (string, required): Database name to retrieve tables from
• schema (string, required): Schema name to retrieve tables from

Example:

{
  "name": "list_tables",
  "arguments": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC"
  }
}

list_views

Retrieve a list of views from a specified database and schema.

Parameters:

• database (string, required): Database name to retrieve views from
• schema (string, required): Schema name to retrieve views from

Example:

{
  "name": "list_views",
  "arguments": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC"
  }
}

describe_table

Retrieve detailed structure information (columns, data types, etc.) for a specified table.

Parameters:

• database (string, required): Database name containing the table
• schema (string, required): Schema name containing the table
• table (string, required): Name of the table to describe

Example:

{
  "name": "describe_table",
  "arguments": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC",
    "table": "CUSTOMERS"
  }
}

Response Format: The describe_table tool returns a structured JSON format:

{
  "table_info": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC",
    "name": "CUSTOMERS",
    "column_count": 4,
    "columns": [
      {
        "name": "ID",
        "data_type": "NUMBER(38,0)",
        "nullable": false,
        "default_value": null,
        "comment": "Primary key",
        "ordinal_position": 1
      }
    ]
  }
}

execute_query

Execute read-only SQL queries and return structured results. Only SELECT, SHOW, DESCRIBE, EXPLAIN and similar read operations are allowed.

Parameters:

• sql (string, required): SQL query to execute (read operations only)
• timeout_seconds (integer, optional): Query timeout in seconds (default: 30, max: 300)

Example:

{
  "name": "execute_query",
  "arguments": {
    "sql": "SELECT * FROM customers LIMIT 10",
    "timeout_seconds": 60
  }
}

Response Format:

{
  "execution_time_ms": 150,
  "row_count": 10,
  "columns": ["id", "name", "email"],
  "rows": [
    {"id": 1, "name": "John", "email": "[email protected]"}
  ],
  "warnings": []
}

sample_table_data

Retrieve sample data from a specified table using Snowflake's SAMPLE ROW clause for efficient data sampling.

Parameters:

• database (string, required): Database name containing the table
• schema (string, required): Schema name containing the table
• table (string, required): Name of the table to sample
• sample_size (integer, optional): Number of sample rows to retrieve (default: 10, minimum: 1)
• columns (array of strings, optional): List of column names to retrieve (if not specified, all columns will be retrieved)

Example:

{
  "name": "sample_table_data",
  "arguments": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC",
    "table": "ORDERS",
    "sample_size": 5,
    "columns": ["order_id", "customer_id", "total"]
  }
}

analyze_table_statistics

Analyze table statistics using Snowflake's high-performance approximation functions (APPROX_PERCENTILE, APPROX_TOP_K, APPROX_COUNT_DISTINCT) to efficiently retrieve statistical information for numeric, string, date, and boolean columns.

Parameters:

• database (string, required): Database name containing the table
• schema (string, required): Schema name containing the table
• table (string, required): Name of the table to analyze
• columns (array of strings, optional): List of column names to analyze (if not specified, all columns will be analyzed)
• top_k_limit (integer, optional): Number of top values to retrieve for string columns (default: 10, max: 100)

Example:

{
  "name": "analyze_table_statistics",
  "arguments": {
    "database": "MY_DATABASE",
    "schema": "PUBLIC",
    "table": "SALES_DATA",
    "columns": ["amount", "region", "order_date"],
    "top_k_limit": 5
  }
}

Response Format: Returns comprehensive statistics tailored to each column type:

• Numeric columns: count, min, max, avg, percentiles (25th, 50th, 75th), distinct count
• String columns: count, min/max length, distinct count, top K most frequent values
• Date columns: count, min/max dates, date range in days, distinct count
• Boolean columns: count, true/false counts and percentages (both NULL-inclusive and NULL-exclusive)

Development

Development Environment Setup

uv sync --all-groups --all-packages

Code Formatting

uv run ruff format .
uv run ruff check --fix .

Code Testing

uv run pytest --doctest-modules .

Troubleshooting

Connection Errors

• Verify that configuration file or environment variables are correctly set
• Check that Snowflake account, username, and password are correct
• Verify network connectivity

Permission Errors

• Ensure the specified user has permission to access the database
• Set the ROLE if necessary

Configuration Priority

Settings are loaded in the following order (later settings take precedence):

1. Configuration file (.mcp_snowflake.toml)
2. Environment variables

License

MIT License