Skip to main content
Glama
Snowflake MCP Server

Snowflake MCP Server

by ncejda-g2

What is Snowflake MCP?

Snowflake MCP Server bridges the gap between your Snowflake data warehouse and AI assistants like Claude. It provides a secure, read-only interface that lets AI help you explore schemas, write queries, and analyze data—all while maintaining enterprise-grade security through SSO authentication.

Related MCP server: Snowflake MCP Server

Features

  • 🔒 Strict Read-Only Access: Multiple layers of protection against write operations

  • 🔑 Flexible Authentication: Browser-based SSO or headless key-pair auth via credential file

  • 💾 Smart Caching: 5-day schema cache for fast metadata access, reducing generic Snowflake schema queries and credit usage

  • 📄 TSV Export: Write query results directly to TSV files, at any size

  • 🛡️ Query Validation: Every query is validated as read-only before execution

  • 🎯 Responsible Token Management: Lightweight outputs to minimize token usage

🚀 Easy Setup For LLM Agents

Already in Claude Code, OpenCode, Cursor, or another AI coding agent? Paste this into your agent:

Set up the Snowflake MCP server for me by following this guide:
https://raw.githubusercontent.com/ncejda-g2/snowflake_mcp_server/main/docs/guide/agent-setup.md

Your agent will walk you through everything interactively — including installing prerequisites. No manual config editing required.

Just configure your MCP client using the examples in the Configuration section below. Requires uv (curl -LsSf https://astral.sh/uv/install.sh | sh).

npx (requires Node.js)

Just configure your MCP client using the examples in the Configuration section below.

From Source

git clone git@github.com:ncejda-g2/snowflake_mcp_server.git
cd snowflake_mcp_server
python3 -m venv snowflake_mcp_env
source snowflake_mcp_env/bin/activate  # On Windows: snowflake_mcp_env\Scripts\activate
pip install -r requirements.txt

Configuration

Edit your ~/.claude.json file:

Using uvx (Recommended):

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "uvx",
      "args": ["snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using npx:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "npx",
      "args": ["-y", "snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using local clone:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "/path/to/snowflake_mcp_server/snowflake_mcp_env/bin/python",
      "args": ["/path/to/snowflake_mcp_server/main.py"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Replace:

  • /path/to/snowflake_mcp_server: Absolute path to your cloned repository (local clone only)

  • your-account: Your Snowflake account identifier (e.g., xy12345.us-east-1)

  • your-email@company.com: Your Snowflake username

  • YOUR_WAREHOUSE: Your Snowflake warehouse name

  • YOUR_ROLE: Your Snowflake role (e.g., ANALYST, PUBLIC)

  • SNOWFLAKE_CREDENTIAL_FILE (optional): Path to a JSON credential file for headless key-pair auth (omit to use browser SSO)

One-click install: Download the latest .mcpb extension and double-click it. Claude Desktop will prompt you for your Snowflake credentials.

Edit your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "uvx",
      "args": ["snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE"
      }
    }
  }
}

Requires uv.

Edit your Cursor settings:

Using uvx (Recommended):

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "uvx",
      "args": ["snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using npx:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "npx",
      "args": ["-y", "snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using local clone:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "/path/to/snowflake_mcp_server/snowflake_mcp_env/bin/python",
      "args": ["/path/to/snowflake_mcp_server/main.py"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Replace:

  • /path/to/snowflake_mcp_server: Absolute path to your cloned repository (local clone only)

  • your-account: Your Snowflake account identifier (e.g., xy12345.us-east-1)

  • your-email@company.com: Your Snowflake username

  • YOUR_WAREHOUSE: Your Snowflake warehouse name

  • YOUR_ROLE: Your Snowflake role (e.g., ANALYST, PUBLIC)

  • SNOWFLAKE_CREDENTIAL_FILE (optional): Path to a JSON credential file for headless key-pair auth (omit to use browser SSO)

Edit your ~/.config/opencode/opencode.json file (global) or opencode.json in your project root (project-level):

Note: OpenCode uses "mcp" (not "mcpServers"), "command" as a single array (not separate command/args), and "environment" (not "env").

Using uvx (Recommended):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "snowflake-readonly": {
      "type": "local",
      "command": ["uvx", "snowflake-readonly-mcp"],
      "environment": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using npx:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "snowflake-readonly": {
      "type": "local",
      "command": ["npx", "-y", "snowflake-readonly-mcp"],
      "environment": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using local clone:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "snowflake-readonly": {
      "type": "local",
      "command": ["/path/to/snowflake_mcp_server/snowflake_mcp_env/bin/python", "/path/to/snowflake_mcp_server/main.py"],
      "environment": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Replace:

  • /path/to/snowflake_mcp_server: Absolute path to your cloned repository (local clone only)

  • your-account: Your Snowflake account identifier (e.g., xy12345.us-east-1)

  • your-email@company.com: Your Snowflake username

  • YOUR_WAREHOUSE: Your Snowflake warehouse name

  • YOUR_ROLE: Your Snowflake role (e.g., ANALYST, PUBLIC)

  • SNOWFLAKE_CREDENTIAL_FILE (optional): Path to a JSON credential file for headless key-pair auth (omit to use browser SSO)

Edit your ~/.gemini/settings.json file:

Using uvx (Recommended):

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "uvx",
      "args": ["snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using npx:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "npx",
      "args": ["-y", "snowflake-readonly-mcp"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Using local clone:

{
  "mcpServers": {
    "snowflake-readonly": {
      "command": "/path/to/snowflake_mcp_server/snowflake_mcp_env/bin/python",
      "args": ["/path/to/snowflake_mcp_server/main.py"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USERNAME": "your-email@company.com",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_ROLE": "YOUR_ROLE",
        "SNOWFLAKE_CREDENTIAL_FILE": "/path/to/credentials.json"  // optional — omit to use browser SSO
      }
    }
  }
}

Replace:

  • /path/to/snowflake_mcp_server: Absolute path to your cloned repository (local clone only)

  • your-account: Your Snowflake account identifier (e.g., xy12345.us-east-1)

  • your-email@company.com: Your Snowflake username

  • YOUR_WAREHOUSE: Your Snowflake warehouse name

  • YOUR_ROLE: Your Snowflake role (e.g., ANALYST, PUBLIC)

  • SNOWFLAKE_CREDENTIAL_FILE (optional): Path to a JSON credential file for headless key-pair auth (omit to use browser SSO)

Available Commands

The server provides powerful tools for interacting with Snowflake:

Tool

Description

refresh_catalog

Scan and cache all database schemas

show_tables

Browse database hierarchy with pattern filters (like SHOW TABLES)

find_tables

Search for tables by keyword across all databases

describe_table

View detailed column information (like DESCRIBE TABLE)

execute_query

Run read-only SQL queries (inline, or auto-spill large results to a temp file)

execute_query_to_file

Execute a query and write its results to a TSV / CSV file at a chosen path (any size)

📚 Documentation


Available Tools

6 tools
describe_tableDescribe TableA

Get detailed column information for a specific table.

USE THIS WHEN: You need column names, types, and constraints to write a query.
Like SQL's: DESCRIBE TABLE database.schema.table

RETURNS: Detailed column information
- For each column: name, data_type, nullable, position, default, comment, is_primary_key

HOW IT WORKS:
- Looks up table in cache; fetches column details on-demand if not yet loaded
- First call for a table queries Snowflake live (~200ms), subsequent calls use cache
- If table not in cache at all, returns error (use show_tables or find_tables first)

Note: To get sample data rows, use execute_query tool separately.

Parameters:
- database: Database name
- schema: Schema name
- table: Table name

Examples:
- describe_table("SALES_DB", "PUBLIC", "CUSTOMERS")
- describe_table("GDC", "STAGING", "ADMIN__CATEGORIES")

Inputs: table (required), schema (required), database (required).

execute_queryExecute QueryA

Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, WITH) and return results.

Requires a populated schema cache; auto-refreshes on first use if empty.

Parameters:
- sql: read-only SQL query
- database: optional database context
- schema: optional schema context

Returns a compact TEXT payload (not JSON): a `key: value` header
(status, rows, cols, execution_time, query_id), a `---` separator, then a
result block whose shape depends on row count:
- ONE row: aligned `NAME  value` lines (one column per line), any width.
- 2+ narrow rows: positional TSV (line 1 = tab-separated column names, one
  row per line after). Parse with awk/cut, e.g. `awk -F'\t' 'NR>1 && $3=="X"'`.
NULL = `\N`; tabs/newlines escaped so each field is one line.

Multi-row results that are wide, tall, or too large auto-spill the COMPLETE
result to a temp `.tsv` file; the payload then carries `results_file` and
`column_index` (name->position) and NO inline rows. Read/grep/awk the file
(it has its own header line); `rows:` is always the true total.

Example: execute_query("SELECT * FROM SALES_DB.PUBLIC.CUSTOMERS LIMIT 10")

Inputs: sql (required), schema, database.

execute_query_to_fileExecute Query To FileA

Writes read-only query results to a file at a path you choose.

Use when the result needs to land at a specific path -- to share or persist.
Format follows the extension: `.csv` writes CSV (NULL = empty field);
anything else writes TSV (same as execute_query: tab-delimited, NULL = `\N`).

Parameters:
- sql: read-only SQL (SELECT, SHOW, DESCRIBE, WITH)
- file_path: output path (absolute recommended; end with `.csv` for CSV,
  else `.tsv` is used/appended)
- database: optional database context
- schema: optional schema context
- timeout_seconds: query timeout (default 300, max 3600)

Requires a populated schema cache. Will not overwrite an existing file.

Example: execute_query_to_file("SELECT * FROM t", "/tmp/export.csv")

Inputs: sql (required), file_path (required), schema, database, +1 more.

find_tablesFind TablesA

Search for tables by keyword across ALL databases.

USE THIS WHEN: You don't know where a table is, but know part of its name or purpose.
Matches against both table names AND table comments (so a cryptically-named
table is still found when its comment mentions the term).

RETURNS (small result): flat list of matches
- [{database, schema, table, type, full_name}, ...]
  Note: neither the comment nor a column count is returned. The comment is the
  one unbounded field (can be a multi-KB doc-block); a column count does not
  help locate a table. For a table's comment and columns, use describe_table.

RETURNS (broad result): when too many tables match to return inline, the
COMPLETE result is written to a temp `.tsv` file and the response is instead a
compact summary built to help you NARROW: `total_hits`, `results_file`, a
bounded `top_groups` breakdown of the top database.schema clusters (with a
`(+X more groups, Y hits)` tail marker), and a `spilled` hint. To narrow, call
show_tables with database_pattern/schema_pattern from top_groups and/or a more
specific table_pattern -- don't blindly re-search.

HOW IT WORKS:
- Auto-refreshes cache if expired/empty (requires Snowflake auth on first use)
- Uses cached data if available (no auth needed)
- Searches table names and comments for the keyword (case-insensitive)

Parameters:
- search_term: Keyword to search for (case-insensitive)

Examples:
- find_tables("customer") - Find all customer-related tables across all databases
- find_tables("revenue") - Find revenue tables anywhere
- find_tables("staging") - Find tables with "staging" in name or comment

Inputs: search_term (required).

refresh_catalogRefresh CatalogA

Refresh the schema catalog by scanning all accessible Snowflake databases.

This tool queries INFORMATION_SCHEMA across all databases to build a comprehensive
index of tables, schemas, and columns. The cache has a 5-day TTL.

Use this tool when:
- First connecting to Snowflake
- Schema changes have been made
- Cache has expired (after 5 days)

Parameters:
- force: Force refresh even if cache is not expired (default: false)
- resume: Resume from checkpoints if they exist (default: true)

Inputs: force, resume.

show_tablesShow TablesA

Browse databases, schemas, and tables using pattern-based filtering.

USE THIS WHEN: You want to explore what databases/schemas exist, or need to filter by exact patterns.
Like SQL's: SHOW TABLES IN database LIKE 'pattern'

RETURNS (small result): hierarchical tree
- database → schema → list of tables

RETURNS (broad result): when the matching tree is too large to return inline
(e.g. show_tables() with no filter, or a broad database_pattern matching tens
of thousands of tables), the COMPLETE tree is written to a temp `.json` file
and the response is instead a compact summary built to help you NARROW:
`total_tables`, `total_schemas`, `results_file`, and a bounded breakdown that
adapts to what's left to narrow -- `top_schemas` (db.schema=count) when the
result is a single database, else `top_databases` (db=count) -- each with a
`(+X more ..., Y tables)` tail marker, plus a `spilled` hint.

To act on a spilled result, prefer RE-CALLING show_tables with a tighter
database_pattern/schema_pattern (served from cache, no Snowflake) until it
fits inline. To read results_file directly instead -- it is compact JSON
nested THREE levels deep, `{"DB": {"SCHEMA": ["TABLE", ...]}}` (so table
names are the innermost array, not a key) -- list its schemas WITHOUT loading
every table name into context:
  jq -r 'to_entries[]|.key as $d|.value|keys[]|"\($d).\(.)"' <results_file>
or, if jq is unavailable:
  python3 -c "import json,sys;d=json.load(open(sys.argv[1]));print(chr(10).join(f'{db}.{s}' for db,sc in d.items() for s in sc))" <results_file>
Mind the nesting depth when counting: `jq '[.[][][]]|length'` counts TABLES
(three flattens to reach the leaf array); `jq '[.[][]]|length'` counts
SCHEMAS. (total_tables/total_schemas in the summary already give both.)

HOW IT WORKS:
- Auto-refreshes cache if expired/empty (requires Snowflake auth on first use)
- Uses cached data if available (no auth needed)
- Pattern matching is case-insensitive substring search

Parameters:
- database_pattern: Filter databases (e.g., "SALES" matches "SALES_DB", "SALES_PROD")
- schema_pattern: Filter schemas (e.g., "PUBLIC")
- table_pattern: Filter tables (e.g., "CUSTOMER" matches "CUSTOMERS", "CUSTOMER_ORDERS")

Examples:
- show_tables() - Browse all databases
- show_tables(database_pattern="SALES") - Only SALES databases
- show_tables(schema_pattern="PUBLIC") - All PUBLIC schemas across databases

Inputs: table_pattern, schema_pattern, database_pattern.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct role: inline query execution, query-to-file export, catalog refresh, hierarchical table browsing, keyword search, and table description. Even the two query tools are clearly separated by output destination, and the two discovery tools differ by browse-versus-search behavior.

    Naming Consistency5/5

    All six tools follow the same imperative verb_noun pattern in snake_case: execute_query, execute_query_to_file, refresh_catalog, show_tables, find_tables, describe_table. The only compound name uses a consistent '_to_file' suffix rather than introducing a different naming style.

    Tool Count5/5

    Six tools is a well-scoped size for a Snowflake read-only exploration server: refresh metadata, browse tables, search tables, describe a table, run a query, and export query results. Each tool earns its place without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full read-only workflow: refresh catalog metadata, discover tables via browsing or keyword search, inspect column details, execute SELECT-style queries, and persist results to a file. Within the server's explicitly read-only scope there are no dead ends or obvious missing operations.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Snowflake databases through SQL queries, table previews, and metadata operations. Features built-in safety checks that block destructive operations and intelligent error handling optimized for AI workflows.
      1
      MIT
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables AI assistants to securely connect to Snowflake data warehouses and execute SQL queries through natural language interactions. Supports multiple authentication methods and provides formatted query results with built-in security controls.
      1
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to execute SQL queries and explore Snowflake databases using natural language, with schema discovery, table inspection, and readonly mode.
      11
      152 npm
      MIT