Snowflake MCP Service

Snowflake MCP 服务

一个模型上下文协议（MCP）服务，可供任何兼容 MCP 的客户端访问 Snowflake 数据库。

此服务实现了模型上下文协议，允许任何 MCP 客户端：

• 在 Snowflake 数据库上执行 SQL 查询
• 自动管理数据库连接生命周期（连接、超时后重新连接、关闭）
• 处理查询结果和错误
• 安全地执行数据库操作
• 使用密码或密钥对进行身份验证

架构概览

什么是 MCP（模型上下文协议）？

MCP 是一种标准协议，可让应用程序与 AI 模型和外部服务通信。它使 AI 模型能够访问训练数据以外的工具和数据源，通过标准化的通信接口扩展其能力。主要特性包括：

• 基于 stdio 通信（标准输入/输出）
• 结构化的工具定义与发现
• 标准化的工具调用机制
• 结构化的结果传输

系统组件

Snowflake-MCP 服务由几个关键组件组成：

1. MCP 服务 - 实现 MCP 协议并处理客户端请求的核心组件
2. Snowflake 连接管理器 - 管理数据库连接，包括创建、维护和清理
3. 查询处理器 - 在 Snowflake 上执行 SQL 查询并处理结果
4. 身份验证管理器 - 处理不同的身份验证方式（密码或私钥）

通信流程

系统通过以下通信流程运行：

1. MCP 客户端（例如 Claude 或其他兼容 MCP 的应用程序）向 MCP 服务发送请求
2. MCP 服务使用 .env 文件中的凭据向 Snowflake 进行身份验证
3. MCP 服务在 Snowflake 上执行 SQL 查询
4. Snowflake 将结果返回给 MCP 服务
5. MCP 服务对结果进行格式化，并将其发送回 MCP 客户端

此架构可实现 AI 应用程序与 Snowflake 数据库之间的无缝集成，同时确保安全性和高效的连接管理。

安装

1. 克隆此存储库

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

2. 安装依赖项

pip install -r requirements.txt

配置

MCP 客户端配置示例

以下是 Claude Desktop 的配置示例，但此服务适用于任何兼容 MCP 的客户端。每个客户端可能有自己的配置方法：

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

配置参数：

• command：Python 解释器的完整路径。请根据 Python 的安装位置进行修改。
• args：服务脚本的完整路径。请根据存储库的克隆位置进行修改。

不同操作系统的路径示例：

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

Snowflake 配置

在项目根目录中创建 .env 文件，并添加以下配置：

# 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

身份验证选项

此 MCP 服务支持两种身份验证方式：

1. 密码身份验证

   SNOWFLAKE_PASSWORD=your_password      # Your Snowflake password
   

2. 密钥对身份验证

   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
   

   使用密钥对身份验证前，必须先在 Snowflake 中设置密钥对身份验证：

   • 生成密钥对，并向 Snowflake 注册公钥
   • 在计算机上安全地保存私钥文件
   • 在配置中提供私钥文件的完整路径

   有关设置密钥对身份验证的说明，请参阅 Snowflake 密钥对身份验证文档。

如果两种身份验证方式都已配置，服务将优先使用密钥对身份验证。

连接管理

该服务提供自动连接管理功能：

• 自动初始化连接

  • 收到第一个查询时创建连接
  • 验证连接参数

• 连接维护

  • 跟踪连接状态
  • 处理连接超时
  • 连接断开时自动重新连接

• 连接清理

  • 服务停止时正确关闭连接
  • 适当地释放资源

使用方法

标准用法

配置好 MCP 客户端后，服务将自动启动。正常运行时无需手动启动。服务运行后，MCP 客户端即可执行 Snowflake 查询。

在开发测试期间，可以使用以下命令手动启动服务：

python server.py

注意：正常使用时无需手动启动服务。MCP 客户端通常会根据配置管理服务的启动和关闭。

Docker 用法

你也可以使用 Docker 运行服务。建议在生产环境中使用此方法，以确保在不同平台上都能一致地运行。

1. 构建 Docker 镜像：

docker build -t snowflake-mcp .

2. 配置 MCP 客户端以使用 Docker。配置示例：

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

注意：Docker 实现使用 stdio 进行通信，因此无需公开任何端口。

如果在 Docker 中使用密钥对身份验证，则需要挂载私钥文件：

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

并相应地更新配置：

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

功能

• 安全访问 Snowflake 数据库
• 灵活的身份验证（密码或密钥对身份验证）
• 稳健的错误处理和报告
• 自动连接管理
• 查询执行和结果处理
• 兼容任何符合 MCP 规范的客户端

技术详情

核心组件

该实现由多个关键类和模块组成：

• server.py - 入口文件，包含 MCP 服务实现。
• SnowflakeConnection - 处理所有 Snowflake 数据库操作的类，包括：
  • 建立连接和重新连接
  • 执行查询和管理事务
  • 维护和清理连接
• SnowflakeMCPServer - 实现 MCP 协议的主要服务类：
  • 向 MCP 框架注册可用工具
  • 处理来自客户端的工具调用请求
  • 管理连接生命周期

连接生命周期

我们会仔细管理连接生命周期，以确保可靠性：

1. 初始化 - 收到第一个查询时按需创建连接
2. 验证 - 尝试连接前验证连接参数
3. 监控 - 定期测试连接的有效性
4. 恢复 - 连接断开或超时时自动重新连接
5. 清理 - 服务关闭时正确释放资源

MCP 工具接口

该服务向 MCP 客户端提供以下工具：

• execute_query - 在 Snowflake 上执行 SQL 查询并返回结果

  • 输入：SQL 查询字符串
  • 输出：结构化格式的查询结果

• export_to_csv - 在 Snowflake 上执行 SQL 查询并返回结果

  • 输入：SQL 查询字符串
  • 输出：导出的行数。输出文件的文件路径

该实现遵循 MCP 协议实现和 Snowflake 数据库交互的最佳实践。

许可证

本项目基于 MIT License 授权。详情请参阅 LICENSE 文件。

版权所有 (c) 2025 David Amom