Snowflake MCP Service

Um servidor MCP para interagir com bancos de dados Snowflake.

Documentação

Serviço Snowflake MCP

Um servidor Model Context Protocol (MCP) que fornece acesso a bancos de dados Snowflake para qualquer cliente compatível com MCP.

Este servidor implementa o Model Context Protocol para permitir que qualquer cliente MCP:

Execute consultas SQL em bancos de dados Snowflake
Gerencie automaticamente o ciclo de vida da conexão com o banco de dados (conectar, reconectar em caso de timeout, fechar)
Trate resultados de consultas e erros
Execute operações de banco de dados com segurança
Conecte-se usando autenticação por senha ou por par de chaves

Visão Geral da Arquitetura

O que é MCP (Model Context Protocol)?

MCP é um protocolo padrão que permite que aplicações se comuniquem com modelos de IA e serviços externos. Ele permite que modelos de IA acessem ferramentas e fontes de dados além de seus dados de treinamento, expandindo suas capacidades por meio de uma interface de comunicação padronizada. Os principais recursos incluem:

Baseado em comunicação stdio (entrada/saída padrão)
Definição e descoberta estruturada de ferramentas
Mecanismo padronizado de chamada de ferramentas
Transmissão estruturada de resultados

Componentes do Sistema

O servidor Snowflake-MCP consiste em vários componentes principais:

Servidor MCP - Componente central que implementa o protocolo MCP e lida com solicitações de clientes
Gerenciador de Conexão Snowflake - Gerencia conexões com o banco de dados, incluindo criação, manutenção e limpeza
Processador de Consultas - Executa consultas SQL no Snowflake e processa os resultados
Gerenciador de Autenticação - Lida com diferentes métodos de autenticação (senha ou chave privada)

alt text

Fluxo de Comunicação

O sistema funciona por meio do seguinte fluxo de comunicação:

Um Cliente MCP (como Claude ou outra aplicação compatível com MCP) envia uma solicitação ao Servidor MCP
O Servidor MCP autentica com o Snowflake usando credenciais do arquivo .env
O Servidor MCP executa consultas SQL no Snowflake
O Snowflake retorna os resultados ao Servidor MCP
O Servidor MCP formata e envia os resultados de volta ao Cliente MCP

alt text

Esta arquitetura permite integração perfeita entre aplicações de IA e bancos de dados Snowflake, mantendo segurança e gerenciamento eficiente de conexões.

Instalação

Clone este repositório

git clone https://github.com/davidamom/snowflake-mcp.git

Instale as dependências

pip install -r requirements.txt

Configuração

Exemplo de Configuração do Cliente MCP

Abaixo está um exemplo de configuração para o Claude Desktop, mas este servidor funciona com qualquer cliente compatível com MCP. Cada cliente pode ter seu próprio método de configuração:

{
  "mcpServers": {
    "snowflake": {
      "command": "C:\\Users\\YourUsername\\path\\to\\python.exe",
      "args": ["C:\\path\\to\\snowflake-mcp\\server.py"]
    }
  }
}

Parâmetros de configuração:

command: Caminho completo para o seu interpretador Python. Modifique isso de acordo com a localização da sua instalação do Python.
args: Caminho completo para o script do servidor. Modifique isso de acordo com onde você clonou o repositório.

Exemplos de caminhos para diferentes sistemas operacionais:

Windows:

{
  "mcpServers": {
    "snowflake": {
      "command": "C:\\Users\\YourUsername\\anaconda3\\python.exe",
      "args": ["C:\\Path\\To\\snowflake-mcp\\server.py"]
    }
  }
}

MacOS/Linux:

{
  "mcpServers": {
    "snowflake": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/snowflake-mcp/server.py"]
    }
  }
}

Configuração do Snowflake

Crie um arquivo .env no diretório raiz do projeto e adicione a seguinte configuração:

# Snowflake Configuration - Basic Info
SNOWFLAKE_USER=your_username          # Your Snowflake username
SNOWFLAKE_ACCOUNT=YourAccount.Region  # Example: MyOrg.US-WEST-2
SNOWFLAKE_DATABASE=your_database      # Your database
SNOWFLAKE_WAREHOUSE=your_warehouse    # Your warehouse
SNOWFLAKE_ROLE=your_role              # Your role

# Authentication - Choose one method

Opções de Autenticação

Este servidor MCP suporta dois métodos de autenticação:

Autenticação por Senha

SNOWFLAKE_PASSWORD=your_password      # Your Snowflake password

Autenticação por Par de Chaves
```
SNOWFLAKE_PRIVATE_KEY_FILE=/path/to/rsa_key.p8     # Path to private key file 
SNOWFLAKE_PRIVATE_KEY_PASSPHRASE=your_passphrase   # Optional: passphrase if key is encrypted
```
Para autenticação por par de chaves, você deve primeiro configurar a autenticação por par de chaves com o Snowflake:
- Gere um par de chaves e registre a chave pública com o Snowflake
- Armazene o arquivo de chave privada com segurança na sua máquina
- Forneça o caminho completo para o arquivo de chave privada na configuração
Para instruções sobre como configurar a autenticação por par de chaves, consulte a documentação do Snowflake sobre autenticação por par de chaves.

Se ambos os métodos de autenticação estiverem configurados, o servidor priorizará a autenticação por par de chaves.

Gerenciamento de Conexão

O servidor fornece recursos automáticos de gerenciamento de conexão:

Inicialização automática da conexão
- Cria a conexão quando a primeira consulta é recebida
- Valida os parâmetros da conexão
Manutenção da conexão
- Mantém o controle do estado da conexão
- Lida com timeouts de conexão
- Reconecta automaticamente se a conexão for perdida
Limpeza da conexão
- Fecha corretamente as conexões quando o servidor é interrompido
- Libera recursos adequadamente

Uso

Uso Padrão

O servidor iniciará automaticamente quando configurado com seu cliente MCP. Nenhuma inicialização manual é necessária na operação normal. Uma vez que o servidor esteja em execução, seu cliente MCP poderá executar consultas no Snowflake.

Para testes de desenvolvimento, você pode iniciar o servidor manualmente usando:

python server.py

Nota: A inicialização manual do servidor não é necessária para uso normal. O cliente MCP normalmente gerenciará a inicialização e o desligamento do servidor com base na configuração.

Uso com Docker

Você também pode executar o servidor usando Docker. Este método é recomendado para ambientes de produção e garante execução consistente em diferentes plataformas.

Construa a imagem Docker:

docker build -t snowflake-mcp .

Configure seu cliente MCP para usar Docker. Exemplo de configuração:

{
  "mcpServers": {
    "snowflake-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "snowflake-mcp"
      ],
      "env": {
        "SNOWFLAKE_USER": "your_username",
        "SNOWFLAKE_ACCOUNT": "your_account",
        "SNOWFLAKE_DATABASE": "your_database",
        "SNOWFLAKE_WAREHOUSE": "your_warehouse",
        "SNOWFLAKE_PASSWORD": "your_password",
        "SNOWFLAKE_ROLE": "your_role"
        
      }
    }
  }
}

Nota: A implementação Docker usa stdio para comunicação, portanto nenhuma porta precisa ser exposta.

Se estiver usando autenticação por par de chaves com Docker, você precisará montar seu arquivo de chave privada:

docker run -i -v /path/to/your/key.p8:/app/rsa_key.p8:ro snowflake-mcp

E atualizar sua configuração de acordo:

{
  "mcpServers": {
    "Snowflake-Docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-v",
        "/path/to/your/key.p8:/app/rsa_key.p8:ro",
        //optional
        "-v",
        "/path/to/export/dir/:/export/"
        "snowflake-mcp"
      ],
      "env": {
        "SNOWFLAKE_USER": "your_username",
        "SNOWFLAKE_ACCOUNT": "your_account",
        "SNOWFLAKE_DATABASE": "your_database",
        "SNOWFLAKE_WAREHOUSE": "your_warehouse",
        "SNOWFLAKE_ROLE": "your_role",
        "SNOWFLAKE_PRIVATE_KEY_FILE": "path_for_your_private_key",
        "SNOWFLAKE_PRIVATE_KEY_PASSPHRASE": "your_password_for_private_key"
      }
    }
  }
}

Recursos

Acesso seguro ao banco de dados Snowflake
Autenticação flexível (senha ou autenticação por par de chaves)
Tratamento robusto de erros e relatórios
Gerenciamento automático de conexão
Execução de consultas e processamento de resultados
Compatível com qualquer cliente compatível com MCP

Detalhes Técnicos

Componentes Principais

A implementação consiste em várias classes e módulos principais:

server.py - O ponto de entrada principal contendo a implementação do servidor MCP.
SnowflakeConnection - Classe que lida com todas as operações do banco de dados Snowflake, incluindo:
- Estabelecimento e reconexão de conexão
- Execução de consultas e gerenciamento de transações
- Manutenção e limpeza de conexão
SnowflakeMCPServer - A classe principal do servidor que implementa o protocolo MCP:
- Registra ferramentas disponíveis com o framework MCP
- Lida com solicitações de chamada de ferramentas de clientes
- Gerencia o ciclo de vida das conexões

Ciclo de Vida da Conexão

O ciclo de vida da conexão é cuidadosamente gerenciado para garantir confiabilidade:

Inicialização - As conexões são criadas de forma preguiçosa quando a primeira consulta é recebida
Validação - Os parâmetros da conexão são validados antes de tentar conectar
Monitoramento - As conexões são testadas regularmente quanto à validade
Recuperação - Reconexão automática se a conexão for perdida ou expirar
Limpeza - Liberação adequada de recursos quando o servidor é desligado

Interface de Ferramentas MCP

O servidor expõe as seguintes ferramentas aos clientes MCP:

execute_query - Executa uma consulta SQL no Snowflake e retorna os resultados
- Entrada: string de consulta SQL
- Saída: Resultados da consulta em formato estruturado
export_to_csv - Executa uma consulta SQL no Snowflake e retorna os resultados
- Entrada: string de consulta SQL
- Saída: Número de linhas exportadas. Caminho do arquivo do arquivo de saída

Esta implementação segue as melhores práticas tanto para a implementação do protocolo MCP quanto para a interação com o banco de dados Snowflake.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.