[](https://pypi.org/project/mcp-snowflake-server-nsp/) • [](https://codecov.io/gh/nsphung/mcp-snowflake-server) • [](https://pypi.org/project/mcp-snowflake-server-nsp/) • [](https://hub.docker.com/r/nsphung/mcp-snowflake-server-nsp) • [](https://opensource.org/licenses/MIT)
| | |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test | [](https://github.com/nsphung/mcp-snowflake-server/actions/workflows/test.yml)  [](https://github.com/nsphung/mcp-snowflake-server/actions/workflows/docker-check.yml) |
| Lint | [](https://github.com/nsphung/mcp-snowflake-server/actions/workflows/lint.yml) [](https://github.com/astral-sh/ruff) [](http://mypy-lang.org/) [](https://github.com/j178/prek) [](https://oxc.rs/docs/guide/usage/formatter) |
| Meta | [](./CODE_OF_CONDUCT.md) [](https://modelcontextprotocol.io/) [](https://www.python.org/) [](https://www.python.org/) |
| Security |  [](https://github.com/nsphung/mcp-snowflake-server/actions/workflows/github-code-scanning/codeql) [](https://scorecard.dev/viewer/?uri=github.com/nsphung/mcp-snowflake-server) [](https://socket.dev/pypi/package/mcp-snowflake-server-nsp) |
| Best Practices | [](https://www.bestpractices.dev/projects/12747) [](https://www.bestpractices.dev/projects/12747) |
| Documentation | [](https://deepwiki.com/nsphung/mcp-snowflake-server) |
---
# Snowflake MCP Server NSP
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://docs.docker.com/dhi/), nonroot user, no shell in runtime)
---
## Table of Contents
- [Snowflake MCP Server NSP](#snowflake-mcp-server-nsp)
- [Table of Contents](#table-of-contents)
- [Quick Start](#quick-start)
- [Claude Code](#claude-code)
- [Visual Studio Code (VSCode)](#visual-studio-code-vscode)
- [OpenCode](#opencode)
- [Components](#components)
- [Resources](#resources)
- [Tools](#tools)
- [Query Tools](#query-tools)
- [Schema Tools](#schema-tools)
- [Analysis Tools](#analysis-tools)
- [Authentication](#authentication)
- [Password](#password)
- [Key-Pair](#key-pair)
- [External Browser](#external-browser)
- [OAuth 2.0 Client Credentials](#oauth-20-client-credentials)
- [OAuth Bearer Token](#oauth-bearer-token)
- [TOML Connection File (Recommended)](#toml-connection-file-recommended)
- [Installation](#installation)
- [Via UVX](#via-uvx)
- [Via Docker Hub](#via-docker-hub)
- [Configuration Reference](#configuration-reference)
- [Exclusion Patterns](#exclusion-patterns)
- [License](#license)
- [Fork and Attribution](#fork-and-attribution)
---
## 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** — [](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522snowflake%2522%252C%2522command%2522%253A%2522uvx%2522%252C%2522args%2522%253A%255B%2522--python%253D3.13%2522%252C%2522--from%2522%252C%2522mcp-snowflake-server-nsp%2522%252C%2522mcp_snowflake_server%2522%255D%257D) [](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522snowflake%2522%252C%2522command%2522%253A%2522uvx%2522%252C%2522args%2522%253A%255B%2522--python%253D3.13%2522%252C%2522--from%2522%252C%2522mcp-snowflake-server-nsp%2522%252C%2522mcp_snowflake_server%2522%255D%257D)
**Docker** — [](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522snowflake%2522%252C%2522command%2522%253A%2522docker%2522%252C%2522args%2522%253A%255B%2522run%2522%252C%2522--rm%2522%252C%2522-i%2522%252C%2522nsphung%252Fmcp-snowflake-server-nsp%2522%255D%257D) [](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522snowflake%2522%252C%2522command%2522%253A%2522docker%2522%252C%2522args%2522%253A%255B%2522run%2522%252C%2522--rm%2522%252C%2522-i%2522%252C%2522nsphung%252Fmcp-snowflake-server-nsp%2522%255D%257D)
Or add manually to your MCP client config (e.g. `.vscode/mcp.json`) using `.env` file (see [Authentication](#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](#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](#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](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-connect#using-oauth) 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`](https://github.com/nsphung/mcp-snowflake-server/blob/main/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`](https://pypi.org/project/mcp-snowflake-server-nsp/).
> **Contributing or running from source?** See [`CONTRIBUTING.md`](https://github.com/nsphung/mcp-snowflake-server/blob/HEAD/CONTRIBUTING.md) for local development setup, test commands, formatting, and building the Docker image from source.
---
### Via UVX