io.github.nsphung/mcp-snowflake-server

Official

by nsphung · Python

Snowflake MCP Server

A Snowflake MCP server — SQL queries, schema exploration, and data insights for AI assistants

Query Snowflake databases, explore schemas, and generate data insights for AI assistants.

Topics

mcpmcp-serversnowflakeagentic-aiagentsdatabasemcp-toolsmodel-context-protocoldockerpython3uvxmodelcontextprotocoldocker-image

README.md28 KBView on GitHub

• • • •


Test
Lint
Meta
Security
Best Practices
Documentation

</div>

Snowflake MCP Server NSP

A Model Context Protocol (MCP) server / MCP server that connects AI assistants to Snowflake — enabling SQL queries, schema exploration, and data insights directly from your LLM client.

Highlights:

Multiple authentication methods: password, key-pair, external browser, OAuth 2.0 (client credentials & bearer token), TOML connection files
TOML multi-connection config — manage production, staging, and development environments in one file
Write-safety guard — write operations are disabled by default and must be explicitly enabled
Exclusion patterns — filter out databases, schemas, or tables from discovery
--exclude-json-results flag — reduces LLM context window usage
Selective tool exclusion via --exclude_tools
Prefetch mode — pre-load table schema as MCP resources
Docker support with hardened image (DHI, nonroot user, no shell in runtime)

Snowflake MCP Server NSP

Quick Start

The fastest way to try it — using uvx with a TOML connection file:

bash

# 1. Create a connections file
cat > ~/snowflake_connections.toml << 'EOF'
[myconn]
account = "your_account"
user = "your_user"
password = "your_password"
warehouse = "COMPUTE_WH"
database = "MY_DB"
schema = "PUBLIC"
role = "MYROLE"
EOF

# 2. Run the server
uvx --python=3.13 --from mcp-snowflake-server-nsp mcp_snowflake_server \
  --connections-file ~/snowflake_connections.toml \
  --connection-name myconn

Claude Code

Add to your MCP client config (e.g. claude_desktop_config.json) using snowflake_connections.toml:

jsonc

"mcpServers": {
  "snowflake": {
    "command": "uvx",
    "args": [
      "--python=3.13",
      "--from", "mcp-snowflake-server-nsp",
      "mcp_snowflake_server",
      "--connections-file", "/absolute/path/to/snowflake_connections.toml",
      "--connection-name", "myconn"
    ]
  }
}

Visual Studio Code (VSCode)

uvx —

Docker —

Or add manually to your MCP client config (e.g. .vscode/mcp.json) using .env file (see Authentication):

jsonc

"snowflake": {
      // Snowflake MCP server
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "mcp-snowflake-server-nsp",
        "--python=3.13",
        "mcp_snowflake_server"
      ],
      "envFile": "${workspaceFolder}/.env"
    }

OpenCode

Add to your MCP client config (e.g. opencode.jsonc) with .env file (see Authentication):

jsonc

"snowflake": {
  "type": "local",
  "command": [
    "uvx",
    "--from",
    "mcp-snowflake-server-nsp",
    "--python=3.13",
    "mcp_snowflake_server",
  ],
  "enabled": true,
  "timeout": 300000,
}

Components

Resources

URI	Description
`memo://insights`	A continuously updated memo aggregating data insights appended via `append_insight`.
`context://table/{table_name}`	(Prefetch mode only) Per-table schema summaries including columns and comments.

Tools

Query Tools

Tool	Description	Requires
`read_query`	Execute `SELECT` queries. Input: `query` (string).	—
`write_query`	Execute `INSERT`, `UPDATE`, or `DELETE` queries. Input: `query` (string).	`--allow_write`
`create_table`	Execute `CREATE TABLE` statements. Input: `query` (string).	`--allow_write`

Schema Tools

Tool	Description	Input
`list_databases`	List all databases in the Snowflake instance.	—
`list_schemas`	List all schemas within a database.	`database` (string)
`list_tables`	List all tables within a database and schema.	`database`, `schema` (strings)
`describe_table`	Describe columns of a table (name, type, nullability, default, comment).	`table_name` as `database.schema.table`

Analysis Tools

Tool	Description	Input
`append_insight`	Add a data insight to the `memo://insights` resource.	`insight` (string)

Authentication

Password

Set credentials via environment variables or CLI flags (see Configuration Reference):

bash

SNOWFLAKE_USER="user@example.com"
SNOWFLAKE_ACCOUNT="myaccount"
SNOWFLAKE_AUTHENTICATOR="snowflake"
SNOWFLAKE_PASSWORD="secret"
SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
SNOWFLAKE_DATABASE="MY_DB"
SNOWFLAKE_SCHEMA="PUBLIC"
SNOWFLAKE_ROLE="MYROLE"

Key-Pair

Both RSA (RS256) and ECDSA (ES256, ES384, ES512) private keys are supported (requires snowflake-connector-python ≥ 4.5.0 for ECDSA).

bash

SNOWFLAKE_USER="user@example.com"
SNOWFLAKE_ACCOUNT="myaccount"
SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
SNOWFLAKE_PRIVATE_KEY_FILE="/absolute/path/to/key.p8"
SNOWFLAKE_PRIVATE_KEY_FILE_PWD="passphrase"  # Optional — only if key is encrypted
SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
SNOWFLAKE_DATABASE="MY_DB"
SNOWFLAKE_SCHEMA="PUBLIC"
SNOWFLAKE_ROLE="MYROLE"

Or via CLI: --private_key_file /path/to/key.p8 --private_key_file_pwd passphrase

External Browser

bash

SNOWFLAKE_AUTHENTICATOR="externalbrowser"

Or in a TOML connection entry: authenticator = "externalbrowser"

OAuth 2.0 Client Credentials

Use the OAuth 2.0 client credentials flow to authenticate with a client ID and secret (no user interaction required):

bash

SNOWFLAKE_AUTHENTICATOR="oauth_client_credentials"
SNOWFLAKE_ACCOUNT="myaccount"
SNOWFLAKE_OAUTH_CLIENT_ID="your_client_id"
SNOWFLAKE_OAUTH_CLIENT_SECRET="your_client_secret"
SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL="https://your-idp.example.com/oauth/token"
SNOWFLAKE_OAUTH_SCOPE="session:role:MY_ROLE"  # Optional
SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
SNOWFLAKE_DATABASE="MY_DB"
SNOWFLAKE_SCHEMA="PUBLIC"
SNOWFLAKE_ROLE="MYROLE"

OAuth Bearer Token

Use a pre-fetched OAuth bearer token:

bash

SNOWFLAKE_AUTHENTICATOR="oauth"
SNOWFLAKE_ACCOUNT="myaccount"
SNOWFLAKE_TOKEN="eyJhbGciOiJSUzI1NiJ9..."
SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
SNOWFLAKE_DATABASE="MY_DB"
SNOWFLAKE_SCHEMA="PUBLIC"
SNOWFLAKE_ROLE="MYROLE"

TOML Connection File (Recommended)

Manage multiple environments in a single file. See example_connections.toml for a full template.

toml

[production]
account = "your_account"
user = "your_user"
password = "your_password"
authenticator = "snowflake"
warehouse = "COMPUTE_WH"
database = "PROD_DB"
schema = "PUBLIC"
role = "ACCOUNTADMIN"

[development]
account = "your_account"
user = "dev_user"
authenticator = "externalbrowser"
warehouse = "DEV_WH"
database = "DEV_DB"
schema = "PUBLIC"
role = "DEVELOPER"

[reporting]
account = "your_account"
user = "reporting_user"
authenticator = "snowflake_jwt"
private_key_file = "/path/to/private_key.pem"
private_key_file_pwd = "passphrase"  # Optional
warehouse = "REPORTING_WH"
database = "REPORTING_DB"
schema = "REPORTS"
role = "REPORTING_ROLE"

[analytics_oauth]
account = "your_account"
authenticator = "oauth_client_credentials"
oauth_client_id = "your_client_id"
oauth_client_secret = "your_client_secret"
oauth_token_request_url = "https://your-idp.example.com/oauth/token"
oauth_scope = "session:role:ANALYTICS_ROLE"  # Optional
warehouse = "ANALYTICS_WH"
database = "ANALYTICS_DB"
schema = "PUBLIC"
role = "ANALYTICS_ROLE"

Pass the file with --connections-file and select a profile with --connection-name. Both flags are required together.

Installation

The package is published on PyPI as mcp-snowflake-server-nsp.

Contributing or running from source? See CONTRIBUTING.md for local development setup, test commands, formatting, and building the Docker image from source.

Via UVX

<details> <summary>TOML configuration (recommended)</summary>

jsonc

"mcpServers": {
  "snowflake_production": {
    "command": "uvx",
    "args": [
      "--python=3.13",
      "--from", "mcp-snowflake-server-nsp",
      "mcp_snowflake_server",
      "--connections-file", "/path/to/snowflake_connections.toml",
      "--connection-name", "production"
      // Optional flags — see Configuration Reference
    ]
  },
  "snowflake_staging": {
    "command": "uvx",
    "args": [
      "--python=3.13",
      "--from", "mcp-snowflake-server-nsp",
      "mcp_snowflake_server",
      "--connections-file", "/path/to/snowflake_connections.toml",
      "--connection-name", "staging"
    ]
  }
}

</details> <details> <summary>Individual parameters</summary>

jsonc

"mcpServers": {
  "snowflake": {
    "command": "uvx",
    "args": [
      "--python=3.13",
      "--from", "mcp-snowflake-server-nsp",
      "mcp_snowflake_server",
      "--account", "your_account",
      "--warehouse", "your_warehouse",
      "--user", "your_user",
      "--password", "your_password",
      "--role", "your_role",
      "--database", "your_database",
      "--schema", "your_schema"
      // Optional: "--private_key_file", "/absolute/path/key.p8"
      // Optional: "--private_key_file_pwd", "passphrase"
      // Optional flags — see Configuration Reference
    ]
  }
}

</details>

Via Docker Hub

The image is published on Docker Hub — no build step required:

bash

docker pull nsphung/mcp-snowflake-server-nsp

Note: -i (--interactive) is required to keep stdin open for the MCP stdio transport. Do not use -d (detach).

<details> <summary>Claude Desktop — <code>claude_desktop_config.json</code></summary>

With .env file (see Authentication):

jsonc

"mcpServers": {
  "snowflake": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "--env-file", "/absolute/path/to/.env",
      "nsphung/mcp-snowflake-server-nsp"
    ]
  }
}

With TOML connections file:

jsonc

"mcpServers": {
  "snowflake": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "-v", "/path/to/snowflake_connections.toml:/app/snowflake_connections.toml:ro",
      "nsphung/mcp-snowflake-server-nsp",
      "--connections-file", "/app/snowflake_connections.toml",
      "--connection-name", "production"
    ]
  }
}

</details> <details> <summary>VS Code — <code>.vscode/mcp.json</code></summary>

With .env file:

jsonc

"snowflake": {
  "type": "stdio",
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "nsphung/mcp-snowflake-server-nsp"
  ],
  "envFile": "${workspaceFolder}/.env"
}

With TOML connections file:

jsonc

"snowflake": {
  "type": "stdio",
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "/path/to/snowflake_connections.toml:/app/snowflake_connections.toml:ro",
    "nsphung/mcp-snowflake-server-nsp",
    "--connections-file", "/app/snowflake_connections.toml",
    "--connection-name", "production"
  ]
}

</details> <details> <summary>OpenCode — <code>opencode.jsonc</code></summary>

jsonc

"snowflake": {
  "type": "local",
  "command": [
    "docker", "run", "--rm", "-i",
    "--env-file", "/absolute/path/to/.env",
    "nsphung/mcp-snowflake-server-nsp"
  ],
  "enabled": true,
  "timeout": 300000
}

</details>

Configuration Reference

All connection parameters can also be set as environment variables (SNOWFLAKE_<PARAM_UPPER>).

Flag	Env var	Default	Description
`--account`	`SNOWFLAKE_ACCOUNT`	—	Snowflake account identifier
`--user`	`SNOWFLAKE_USER`	—	Snowflake username
`--password`	`SNOWFLAKE_PASSWORD`	—	Password (not required for key-pair / SSO)
`--warehouse`	`SNOWFLAKE_WAREHOUSE`	—	Virtual warehouse to use
`--database`	`SNOWFLAKE_DATABASE`	(required)	Default database
`--schema`	`SNOWFLAKE_SCHEMA`	(required)	Default schema
`--role`	`SNOWFLAKE_ROLE`	—	Role to assume
`--private_key_file`	`SNOWFLAKE_PRIVATE_KEY_FILE`	—	Absolute path to RSA or ECDSA (ES256/384/512) private key file (`.p8` / `.pem`)
`--private_key_file_pwd`	`SNOWFLAKE_PRIVATE_KEY_FILE_PWD`	—	Passphrase for encrypted private key
`--connections-file`	—	—	Path to TOML connections file
`--connection-name`	—	—	Connection profile name in TOML file (required with `--connections-file`)
`--allow_write`	—	`false`	Enable `write_query` and `create_table` tools
`--prefetch` / `--no-prefetch`	—	`false`	Pre-load table schema as `context://table/*` resources (disables `list_tables` / `describe_table`)
`--exclude_tools`	—	`[]`	Space-separated list of tool names to disable
`--exclude-json-results`	—	`false`	Omit embedded JSON resources from responses (reduces context window usage)
`--log_dir`	—	—	Directory for log file output
`--log_level`	—	`INFO`	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Exclusion Patterns

Edit runtime_config.json to exclude databases, schemas, or tables from all discovery tools. Patterns are matched case-insensitively as substrings.

json

{
  "exclude_patterns": {
    "databases": ["temp"],
    "schemas": ["temp", "information_schema"],
    "tables": ["temp"]
  }
}

The server loads this file automatically at startup from the working directory.

License

This project is licensed under the MIT License. See the LICENSE file for the full text.

Fork and Attribution

This repository is a fork of isaacwasserman/mcp-snowflake-server.

Upstream authors and contributors retain copyright for their contributions.
Fork-specific changes are maintained by nsphung.
A summary of notable modifications is tracked in NOTICE.

Install

Configuration

Environment variables

SNOWFLAKE_ACCOUNT

Snowflake account identifier

SNOWFLAKE_USER

Snowflake username

SNOWFLAKE_PASSWORDsecret

Password (not required for key-pair / SSO)

SNOWFLAKE_WAREHOUSE

Virtual warehouse to use

SNOWFLAKE_DATABASE

Default database

SNOWFLAKE_SCHEMA

Default schema

SNOWFLAKE_ROLE

Role to assume

SNOWFLAKE_AUTHENTICATOR

Authentication method. Defaults to 'snowflake' if not set. Valid values: snowflake, externalbrowser, snowflake_jwt, oauth, oauth_client_credentials

SNOWFLAKE_PRIVATE_KEY_FILE

Absolute path to .p8 private key file

SNOWFLAKE_PRIVATE_KEY_FILE_PWDsecret

Passphrase for encrypted private key

SNOWFLAKE_OAUTH_CLIENT_ID

OAuth 2.0 client ID (required for oauth_client_credentials authenticator)

SNOWFLAKE_OAUTH_CLIENT_SECRETsecret

OAuth 2.0 client secret (required for oauth_client_credentials authenticator)

SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL

OAuth 2.0 token endpoint URL (required for oauth_client_credentials authenticator)

SNOWFLAKE_OAUTH_SCOPE

OAuth 2.0 scope (optional, e.g. session:role:MY_ROLE)

SNOWFLAKE_TOKENsecret

Pre-fetched OAuth bearer token (required for oauth authenticator)

Arguments

--account

--user

--password

--warehouse

--database

--schema

--role

--authenticator

--private_key_file

--private_key_file_pwd

--connections-file

--connection-name

--allow_write

--prefetch

--exclude_tools

--exclude-json-results

--log_dir

--log_leveldefault INFO

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-snowflake-server": {
      "command": "uvx",
      "args": [
        "mcp-snowflake-server-nsp",
        "--account",
        "--user",
        "--password",
        "--warehouse",
        "--database",
        "--schema",
        "--role",
        "--authenticator",
        "--private_key_file",
        "--private_key_file_pwd",
        "--connections-file",
        "--connection-name",
        "--allow_write",
        "--prefetch",
        "--exclude_tools",
        "--exclude-json-results",
        "--log_dir",
        "--log_level",
        "INFO"
      ],
      "env": {
        "SNOWFLAKE_ACCOUNT": "<YOUR_SNOWFLAKE_ACCOUNT>",
        "SNOWFLAKE_USER": "<YOUR_SNOWFLAKE_USER>",
        "SNOWFLAKE_PASSWORD": "<YOUR_SNOWFLAKE_PASSWORD>",
        "SNOWFLAKE_WAREHOUSE": "<YOUR_SNOWFLAKE_WAREHOUSE>",
        "SNOWFLAKE_DATABASE": "<YOUR_SNOWFLAKE_DATABASE>",
        "SNOWFLAKE_SCHEMA": "<YOUR_SNOWFLAKE_SCHEMA>",
        "SNOWFLAKE_ROLE": "<YOUR_SNOWFLAKE_ROLE>",
        "SNOWFLAKE_AUTHENTICATOR": "<YOUR_SNOWFLAKE_AUTHENTICATOR>",
        "SNOWFLAKE_PRIVATE_KEY_FILE": "<YOUR_SNOWFLAKE_PRIVATE_KEY_FILE>",
        "SNOWFLAKE_PRIVATE_KEY_FILE_PWD": "<YOUR_SNOWFLAKE_PRIVATE_KEY_FILE_PWD>",
        "SNOWFLAKE_OAUTH_CLIENT_ID": "<YOUR_SNOWFLAKE_OAUTH_CLIENT_ID>",
        "SNOWFLAKE_OAUTH_CLIENT_SECRET": "<YOUR_SNOWFLAKE_OAUTH_CLIENT_SECRET>",
        "SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL": "<YOUR_SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL>",
        "SNOWFLAKE_OAUTH_SCOPE": "<YOUR_SNOWFLAKE_OAUTH_SCOPE>",
        "SNOWFLAKE_TOKEN": "<YOUR_SNOWFLAKE_TOKEN>"
      }
    }
  }
}

Topics

Snowflake MCP Server NSP

Table of Contents

Quick Start

Claude Code

Visual Studio Code (VSCode)

OpenCode

Components

Resources

Tools

Query Tools

Schema Tools

Analysis Tools

Authentication

Password

Key-Pair

External Browser

OAuth 2.0 Client Credentials

OAuth Bearer Token

TOML Connection File (Recommended)

Installation

Via UVX

Via Docker Hub

Configuration Reference

Exclusion Patterns

License

Fork and Attribution

Install

Configuration