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

Tools

Query Tools

Schema Tools

Analysis Tools

Authentication

Password

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

SNOWFLAKE_USER="[email protected]"
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="[email protected]"
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

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

"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="[email protected]"
  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:

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

"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="[email protected]"
   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:

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

"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="[email protected]" \
  -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>).

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.