mcp-snowflake-server-nsp 0.8.0

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

Snowflake MCP Server

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

---

Table of Contents

• Snowflake MCP Server
  • 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
    • Locally from Source with VSCode
    • Locally from Source with Claude
    • Docker
  • Configuration Reference
  • Exclusion Patterns
  • Development
  • Documentation & Coverage
  • License
  • Fork and Attribution

---

Quick Start

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

# 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:

"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)

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

"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):

"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):

SNOWFLAKE_USER="[e-mail]"
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

SNOWFLAKE_USER="[e-mail]"
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

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):

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:

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.

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

---

Via UVX

TOML configuration (recommended)

"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"
    ]
  }
}

Individual parameters

"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
    ]
  }
}

---

Locally from Source with VSCode

• Install Visual Studio Code

• Install uv:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Create a .env file with your Snowflake credentials (or use a TOML connection file — see Authentication):

  SNOWFLAKE_USER="[e-mail]"
  SNOWFLAKE_ACCOUNT="myaccount"
  SNOWFLAKE_ROLE="MYROLE"
  SNOWFLAKE_DATABASE="MY_DB"
  SNOWFLAKE_SCHEMA="PUBLIC"
  SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
  SNOWFLAKE_AUTHENTICATOR="snowflake"
  SNOWFLAKE_PASSWORD="secret"
  # Key-pair alternative:
  # SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
  # SNOWFLAKE_PRIVATE_KEY_FILE=/absolute/path/key.p8
  # SNOWFLAKE_PRIVATE_KEY_FILE_PWD="passphrase"
  # Browser SSO alternative:
  # SNOWFLAKE_AUTHENTICATOR="externalbrowser"
  

• (Optional) Edit runtime_config.json to exclude specific databases, schemas, or tables (see Exclusion Patterns).

• Test locally:

  uv --directory /absolute/path/to/mcp_snowflake_server run mcp_snowflake_server
  

• Add to .vscode/mcp.json:

TOML configuration (recommended)

"snowflake-local": {
    "type": "stdio",
    "command": "/absolute/path/to/uv",
    "args": [
      "--python=3.13",
      "--directory", "/absolute/path/to/mcp_snowflake_server",
      "run", "mcp_snowflake_server",
      "--connections-file", "/absolute/path/to/snowflake_connections.toml",
      "--connection-name", "development"
      // Optional flags — see Configuration Reference
    ],
}

Environment variables

"snowflake-local": {
    "type": "stdio",
    "command": "/absolute/path/to/uv",
    "args": [
      "--python=3.13",
      "--directory", "/absolute/path/to/mcp_snowflake_server",
      "run", "mcp_snowflake_server",
      // Optional flags — see Configuration Reference / .env.example file
    ],
    "envFile": "/absolute/path/to/.env"
}

Locally from Source with Claude

1. Install Claude AI Desktop App

2. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Create a .env file with your Snowflake credentials (or use a TOML connection file — see Authentication):

   SNOWFLAKE_USER="[e-mail]"
   SNOWFLAKE_ACCOUNT="myaccount"
   SNOWFLAKE_ROLE="MYROLE"
   SNOWFLAKE_DATABASE="MY_DB"
   SNOWFLAKE_SCHEMA="PUBLIC"
   SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
   SNOWFLAKE_AUTHENTICATOR="snowflake"
   SNOWFLAKE_PASSWORD="secret"
   # Key-pair alternative:
   # SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
   # SNOWFLAKE_PRIVATE_KEY_FILE=/absolute/path/key.p8
   # SNOWFLAKE_PRIVATE_KEY_FILE_PWD="passphrase"
   # Browser SSO alternative:
   # SNOWFLAKE_AUTHENTICATOR="externalbrowser"
   

4. (Optional) Edit runtime_config.json to exclude specific databases, schemas, or tables (see Exclusion Patterns).

5. Test locally:

   uv --directory /absolute/path/to/mcp_snowflake_server run mcp_snowflake_server
   

6. Add to claude_desktop_config.json:

TOML configuration (recommended)

"mcpServers": {
  "snowflake_local": {
    "command": "/absolute/path/to/uv",
    "args": [
      "--python=3.13",
      "--directory", "/absolute/path/to/mcp_snowflake_server",
      "run", "mcp_snowflake_server",
      "--connections-file", "/absolute/path/to/snowflake_connections.toml",
      "--connection-name", "development"
      // Optional flags — see Configuration Reference
    ]
  }
}

Environment variables

"mcpServers": {
  "snowflake_local": {
    "command": "/absolute/path/to/uv",
    "args": [
      "--python=3.13",
      "--directory", "/absolute/path/to/mcp_snowflake_server",
      "run", "mcp_snowflake_server"
      // Optional flags — see Configuration Reference
    ]
  }
}

---

Docker

A Dockerfile is included for containerised deployments:

# Build
docker build -t mcp-snowflake-server .

# Run (pass credentials as environment variables)
docker run --rm \
  -e SNOWFLAKE_USER="[e-mail]" \
  -e SNOWFLAKE_ACCOUNT="myaccount" \
  -e SNOWFLAKE_AUTHENTICATOR="snowflake" \
  -e SNOWFLAKE_PASSWORD="secret" \
  -e SNOWFLAKE_WAREHOUSE="COMPUTE_WH" \
  -e SNOWFLAKE_DATABASE="MY_DB" \
  -e SNOWFLAKE_SCHEMA="PUBLIC" \
  -e SNOWFLAKE_ROLE="MYROLE" \
  mcp-snowflake-server

# Or override the entrypoint arguments directly
docker run --rm mcp-snowflake-server \
  --account your_account \
  --user your_user \
  --authenticator snowflake \
  --password your_password \
  --warehouse COMPUTE_WH \
  --database MY_DB \
  --schema PUBLIC \
  --role MYROLE

---

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 .p8 private key file
--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.

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

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

---

Development

# Install dependencies (including dev tools)
make install

# Lint & auto-fix with Ruff
make ruff

# Run tests
make test

# Run tests with terminal coverage report
make coverage

# Run tests and open HTML coverage report
make coverage-html

# Run the server locally
make run

Requires uv. Dev dependencies include ruff, mypy, pytest, pytest-asyncio, pytest-cov, and pre-commit.

---

Documentation & Coverage

• Full AI-generated documentation:

• Test coverage sunburst:

  

---

License

This project is licensed under the GNU General Public License v3.0. 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.