MCP Snowflake Server NSP

Um servidor MCP Snowflake — consultas SQL, exploração de esquemas e insights de dados para assistentes de IA

Documentação

• • • •


Test
Lint
Meta
Security
Best Practices
Documentation

Snowflake MCP Server NSP

Um servidor Model Context Protocol (MCP) / servidor MCP que conecta assistentes de IA ao Snowflake — permitindo consultas SQL, exploração de esquemas e insights de dados diretamente do seu cliente LLM.

Destaques:

Múltiplos métodos de autenticação: senha, par de chaves, navegador externo, OAuth 2.0 (credenciais de cliente e token bearer), arquivos de conexão TOML
Configuração multi-conexão TOML — gerencie ambientes production, staging e development em um único arquivo
Proteção contra escrita — operações de escrita são desabilitadas por padrão e devem ser explicitamente habilitadas
Padrões de exclusão — filtre bancos de dados, esquemas ou tabelas da descoberta
Flag --exclude-json-results — reduz o uso do contexto do LLM
Exclusão seletiva de ferramentas via --exclude_tools
Modo de pré-busca — pré-carrega o esquema de tabelas como recursos MCP
Suporte a Docker com imagem endurecida (DHI, usuário não-root, sem shell em tempo de execução)

Sumário

Snowflake MCP Server NSP

Início Rápido

A maneira mais rápida de experimentar — usando uvx com um arquivo de conexão TOML:

# 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

Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json) usando 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)

uvx —

Docker —

Ou adicione manualmente à configuração do seu cliente MCP (ex.: .vscode/mcp.json) usando o arquivo .env (veja Autenticação):

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

OpenCode

Adicione à configuração do seu cliente MCP (ex.: opencode.jsonc) com o arquivo .env (veja Autenticação):

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

Componentes

Recursos

URI	Descrição
`memo://insights`	Um memorando continuamente atualizado que agrega insights de dados anexados via `append_insight`.
`context://table/{table_name}`	(Somente modo de pré-busca) Resumos de esquema por tabela, incluindo colunas e comentários.

Ferramentas

Ferramentas de Consulta

Ferramenta	Descrição	Requer
`read_query`	Executa consultas `SELECT`. Entrada: `query` (string).	—
`write_query`	Executa consultas `INSERT`, `UPDATE` ou `DELETE`. Entrada: `query` (string).	`--allow_write`
`create_table`	Executa instruções `CREATE TABLE`. Entrada: `query` (string).	`--allow_write`

Ferramentas de Esquema

Ferramenta	Descrição	Entrada
`list_databases`	Lista todos os bancos de dados na instância Snowflake.	—
`list_schemas`	Lista todos os esquemas dentro de um banco de dados.	`database` (string)
`list_tables`	Lista todas as tabelas dentro de um banco de dados e esquema.	`database`, `schema` (strings)
`describe_table`	Descreve colunas de uma tabela (nome, tipo, nulabilidade, padrão, comentário).	`table_name` como `database.schema.table`

Ferramentas de Análise

Ferramenta	Descrição	Entrada
`append_insight`	Adiciona um insight de dados ao recurso `memo://insights`.	`insight` (string)

Autenticação

Senha

Defina credenciais via variáveis de ambiente ou flags de CLI (veja Referência de Configuração):

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"

Par de Chaves

Chaves privadas RSA (RS256) e ECDSA (ES256, ES384, ES512) são suportadas (requer snowflake-connector-python ≥ 4.5.0 para ECDSA).

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"

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

Navegador Externo

SNOWFLAKE_AUTHENTICATOR="externalbrowser"

Ou em uma entrada de conexão TOML: authenticator = "externalbrowser"

Credenciais de Cliente OAuth 2.0

Use o fluxo de credenciais de cliente OAuth 2.0 para autenticar com um ID de cliente e segredo (sem interação do usuário):

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"

Token Bearer OAuth

Use um token bearer OAuth pré-buscado:

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

Arquivo de Conexão TOML (Recomendado)

Gerencie múltiplos ambientes em um único arquivo. Veja example_connections.toml para um modelo completo.

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

Passe o arquivo com --connections-file e selecione um perfil com --connection-name. Ambas as flags são obrigatórias juntas.

Instalação

O pacote é publicado no PyPI como mcp-snowflake-server-nsp.

Contribuindo ou executando a partir do código-fonte? Veja CONTRIBUTING.md para configuração de desenvolvimento local, comandos de teste, formatação e construção da imagem Docker a partir do código-fonte.

Via UVX

Configuração TOML (recomendada)

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

Parâmetros individuais

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

Via Docker Hub

A imagem é publicada no Docker Hub — nenhuma etapa de build necessária:

docker pull nsphung/mcp-snowflake-server-nsp

Nota: -i (--interactive) é necessário para manter o stdin aberto para o transporte stdio do MCP. Não use -d (detach).

Claude Desktop — claude_desktop_config.json

Com o arquivo .env (veja Autenticação):

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

Com arquivo de conexões TOML:

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

VS Code — .vscode/mcp.json

Com o arquivo .env:

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

Com arquivo de conexões TOML:

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

OpenCode — opencode.jsonc

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

Referência de Configuração

Todos os parâmetros de conexão também podem ser definidos como variáveis de ambiente (SNOWFLAKE_<PARAM_UPPER>).

Flag	Env var	Default	Descrição
`--account`	`SNOWFLAKE_ACCOUNT`	—	Identificador da conta Snowflake
`--user`	`SNOWFLAKE_USER`	—	Nome de usuário do Snowflake
`--password`	`SNOWFLAKE_PASSWORD`	—	Senha (não necessária para par de chaves / SSO)
`--warehouse`	`SNOWFLAKE_WAREHOUSE`	—	Armazém virtual a usar
`--database`	`SNOWFLAKE_DATABASE`	(obrigatório)	Banco de dados padrão
`--schema`	`SNOWFLAKE_SCHEMA`	(obrigatório)	Esquema padrão
`--role`	`SNOWFLAKE_ROLE`	—	Função a assumir
`--private_key_file`	`SNOWFLAKE_PRIVATE_KEY_FILE`	—	Caminho absoluto para o arquivo de chave privada RSA ou ECDSA (ES256/384/512) (`.p8` / `.pem`)
`--private_key_file_pwd`	`SNOWFLAKE_PRIVATE_KEY_FILE_PWD`	—	Frase secreta para chave privada criptografada
`--connections-file`	—	—	Caminho para o arquivo de conexões TOML
`--connection-name`	—	—	Nome do perfil de conexão no arquivo TOML (obrigatório com `--connections-file`)
`--allow_write`	—	`false`	Habilitar as ferramentas `write_query` e `create_table`
`--prefetch` / `--no-prefetch`	—	`false`	Pré-carregar esquema de tabela como recursos `context://table/*` (desabilita `list_tables` / `describe_table`)
`--exclude_tools`	—	`[]`	Lista separada por espaços de nomes de ferramentas a desabilitar
`--exclude-json-results`	—	`false`	Omitir recursos JSON incorporados das respostas (reduz o uso da janela de contexto)
`--log_dir`	—	—	Diretório para saída do arquivo de log
`--log_level`	—	`INFO`	Nível de detalhe do log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Padrões de Exclusão

Edite runtime_config.json para excluir bancos de dados, esquemas ou tabelas de todas as ferramentas de descoberta. Os padrões são correspondidos sem diferenciar maiúsculas de minúsculas como substrings.

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

O servidor carrega este arquivo automaticamente na inicialização a partir do diretório de trabalho.

Licença

Este projeto é licenciado sob a Licença MIT. Veja o arquivo LICENSE para o texto completo.

Fork e Atribuição

Este repositório é um fork de isaacwasserman/mcp-snowflake-server.

Os autores e contribuidores originais mantêm os direitos autorais de suas contribuições.
As alterações específicas do fork são mantidas por nsphung.
Um resumo das modificações notáveis é rastreado em NOTICE.