MCP Snowflake Server NSP

Un servidor MCP de Snowflake: consultas SQL, exploración de esquemas y análisis de datos para asistentes de IA

Documentación

• • • •


Pruebas
Lint
Meta
Seguridad
Mejores prácticas
Documentación

Snowflake MCP Server NSP

Un servidor de Model Context Protocol (MCP) / servidor MCP que conecta asistentes de IA a Snowflake, permitiendo consultas SQL, exploración de esquemas e información de datos directamente desde tu cliente LLM.

Aspectos destacados:

Múltiples métodos de autenticación: contraseña, par de claves, navegador externo, OAuth 2.0 (credenciales de cliente y token de portador), archivos de conexión TOML
Configuración TOML de múltiples conexiones: gestiona los entornos production, staging y development en un solo archivo
Protección de seguridad de escritura: las operaciones de escritura están deshabilitadas por defecto y deben habilitarse explícitamente
Patrones de exclusión: filtra bases de datos, esquemas o tablas del descubrimiento
El indicador --exclude-json-results reduce el uso de la ventana de contexto del LLM
Exclusión selectiva de herramientas mediante --exclude_tools
Modo de precarga: precarga el esquema de tablas como recursos MCP
Soporte Docker con imagen reforzada (DHI, usuario no root, sin shell en tiempo de ejecución)

Tabla de contenido

Snowflake MCP Server NSP

Inicio rápido

La forma más rápida de probarlo: usando uvx con un archivo de conexión 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

Añádelo a la configuración de tu cliente MCP (p. ej., 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 —

O añádelo manualmente a la configuración de tu cliente MCP (p. ej., .vscode/mcp.json) usando el archivo .env (consulta Autenticación):

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

OpenCode

Añádelo a la configuración de tu cliente MCP (p. ej., opencode.jsonc) con el archivo .env (consulta Autenticación):

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

Componentes

Recursos

URI	Descripción
`memo://insights`	Un memo actualizado continuamente que agrega información de datos añadida mediante `append_insight`.
`context://table/{table_name}`	(Solo modo de precarga) Resúmenes de esquema por tabla, incluyendo columnas y comentarios.

Herramientas

Herramientas de consulta

Herramienta	Descripción	Requiere
`read_query`	Ejecuta consultas `SELECT`. Entrada: `query` (cadena).	—
`write_query`	Ejecuta consultas `INSERT`, `UPDATE` o `DELETE`. Entrada: `query` (cadena).	`--allow_write`
`create_table`	Ejecuta sentencias `CREATE TABLE`. Entrada: `query` (cadena).	`--allow_write`

Herramientas de esquema

Herramienta	Descripción	Entrada
`list_databases`	Lista todas las bases de datos en la instancia de Snowflake.	—
`list_schemas`	Lista todos los esquemas dentro de una base de datos.	`database` (cadena)
`list_tables`	Lista todas las tablas dentro de una base de datos y esquema.	`database`, `schema` (cadenas)
`describe_table`	Describe las columnas de una tabla (nombre, tipo, nulabilidad, valor predeterminado, comentario).	`table_name` como `database.schema.table`

Herramientas de análisis

Herramienta	Descripción	Entrada
`append_insight`	Añade una información de datos al recurso `memo://insights`.	`insight` (cadena)

Autenticación

Contraseña

Configura las credenciales mediante variables de entorno o indicadores de CLI (consulta la Referencia de configuración):

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 claves

Se admiten claves privadas RSA (RS256) y ECDSA (ES256, ES384, ES512) (requiere 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"

O mediante CLI: --private_key_file /path/to/key.p8 --private_key_file_pwd passphrase

Navegador externo

SNOWFLAKE_AUTHENTICATOR="externalbrowser"

O en una entrada de conexión TOML: authenticator = "externalbrowser"

Credenciales de cliente OAuth 2.0

Usa el flujo de credenciales de cliente OAuth 2.0 para autenticarte con un ID de cliente y un secreto (no se requiere interacción del usuario):

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 de portador OAuth

Usa un token de portador OAuth obtenido previamente:

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

Archivo de conexión TOML (recomendado)

Gestiona múltiples entornos en un solo archivo. Consulta example_connections.toml para ver una plantilla completa.

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

Pasa el archivo con --connections-file y selecciona un perfil con --connection-name. Ambos indicadores son obligatorios juntos.

Instalación

El paquete está publicado en PyPI como mcp-snowflake-server-nsp.

¿Contribuyes o ejecutas desde el código fuente? Consulta CONTRIBUTING.md para la configuración de desarrollo local, comandos de prueba, formato y creación de la imagen Docker desde el código fuente.

Mediante UVX

Configuración 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 individuales

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

Mediante Docker Hub

La imagen está publicada en Docker Hub; no se requiere paso de compilación:

docker pull nsphung/mcp-snowflake-server-nsp

Nota: -i (--interactive) es necesario para mantener stdin abierto para el transporte stdio de MCP. No use -d (detach).

Claude Desktop — claude_desktop_config.json

Con el archivo .env (ver Autenticación):

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

Con el archivo de conexiones 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

Con el archivo .env:

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

Con el archivo de conexiones 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
}

Referencia de Configuración

Todos los parámetros de conexión también se pueden establecer como variables de entorno (SNOWFLAKE_<PARAM_UPPER>).

Indicador	Variable de entorno	Predeterminado	Descripción
`--account`	`SNOWFLAKE_ACCOUNT`	—	Identificador de cuenta de Snowflake
`--user`	`SNOWFLAKE_USER`	—	Nombre de usuario de Snowflake
`--password`	`SNOWFLAKE_PASSWORD`	—	Contraseña (no requerida para par de claves / SSO)
`--warehouse`	`SNOWFLAKE_WAREHOUSE`	—	Almacén virtual a utilizar
`--database`	`SNOWFLAKE_DATABASE`	(requerido)	Base de datos predeterminada
`--schema`	`SNOWFLAKE_SCHEMA`	(requerido)	Esquema predeterminado
`--role`	`SNOWFLAKE_ROLE`	—	Rol a asumir
`--private_key_file`	`SNOWFLAKE_PRIVATE_KEY_FILE`	—	Ruta absoluta al archivo de clave privada RSA o ECDSA (ES256/384/512) (`.p8` / `.pem`)
`--private_key_file_pwd`	`SNOWFLAKE_PRIVATE_KEY_FILE_PWD`	—	Frase de contraseña para clave privada cifrada
`--connections-file`	—	—	Ruta al archivo de conexiones TOML
`--connection-name`	—	—	Nombre del perfil de conexión en el archivo TOML (requerido con `--connections-file`)
`--allow_write`	—	`false`	Habilitar las herramientas `write_query` y `create_table`
`--prefetch` / `--no-prefetch`	—	`false`	Precargar el esquema de tablas como recursos `context://table/*` (deshabilita `list_tables` / `describe_table`)
`--exclude_tools`	—	`[]`	Lista separada por espacios de nombres de herramientas a deshabilitar
`--exclude-json-results`	—	`false`	Omitir recursos JSON incrustados de las respuestas (reduce el uso de la ventana de contexto)
`--log_dir`	—	—	Directorio para la salida del archivo de registro
`--log_level`	—	`INFO`	Nivel de detalle del registro: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Patrones de Exclusión

Edite runtime_config.json para excluir bases de datos, esquemas o tablas de todas las herramientas de descubrimiento. Los patrones se comparan sin distinción de mayúsculas y minúsculas como subcadenas.

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

El servidor carga este archivo automáticamente al inicio desde el directorio de trabajo.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo LICENSE para ver el texto completo.

Bifurcación y Atribución

Este repositorio es una bifurcación de isaacwasserman/mcp-snowflake-server.

Los autores y contribuyentes originales conservan los derechos de autor de sus contribuciones.
Los cambios específicos de la bifurcación son mantenidos por nsphung.
Un resumen de las modificaciones notables se registra en NOTICE.