使用说明

项目简介

该项目是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于安全地查询 Snowflake 数据库中的数据。它允许大型语言模型（LLM）客户端，如 Claude，通过标准的 MCP 协议访问 Snowflake 数据库，进行只读数据分析和报告，而无需修改任何数据。

主要功能点

安全连接 Snowflake: 使用服务帐户认证和私钥安全连接到 Snowflake 数据库。
MCP 协议兼容: 实现了 MCP 协议规范，可以与任何 MCP 客户端（如 Claude）无缝集成。
只读操作: 所有操作均为只读，保障数据安全，防止意外修改数据库信息。
丰富的数据查询工具: 提供多种预定义的工具，用于列出数据库、视图、描述视图结构、查询视图数据以及执行自定义 SQL 查询（仅限 SELECT）。
数据格式化输出: 查询结果以 Markdown 表格形式返回，方便 LLM 理解和展示。
安全防护: 限制查询类型为 SELECT，自动添加 LIMIT 限制结果集大小，并进行 SQL 注入防护。

安装步骤

环境准备:
- 确保已安装 Python 3.12 或更高版本。
- 确保已配置 Snowflake 服务帐户（用户名 + 私钥）。
- 推荐安装 uv 包管理器（可选，但推荐使用）。

克隆仓库:

git clone https://github.com/dynamike/mcp-server-snowflake.git
cd mcp-server-snowflake

安装依赖:
```
uv pip install -e .
```

配置环境变量:

复制 '.env.example' 文件并重命名为 '.env'。

根据您的 Snowflake 账户信息，编辑 '.env' 文件，填写以下配置项：

SNOWFLAKE_ACCOUNT=youraccount.region  # 您的 Snowflake 账户
SNOWFLAKE_USER=your_service_account_username  # 服务帐户用户名
SNOWFLAKE_PRIVATE_KEY_PATH=/absolute/path/to/your/rsa_key.p8 # 私钥文件绝对路径
SNOWFLAKE_WAREHOUSE=your_warehouse # Snowflake 仓库名
SNOWFLAKE_DATABASE=your_database # 默认数据库名 (可选)
SNOWFLAKE_SCHEMA=your_schema # 默认 Schema 名 (可选)
SNOWFLAKE_ROLE=your_role # 默认角色名 (可选)

请务必妥善保管 '.env' 文件，不要将其提交到版本控制系统。

服务器配置

为了让 MCP 客户端（例如 Claude Desktop）连接到此 Snowflake MCP 服务器，您需要配置服务器的启动命令和参数。以下是 Claude Desktop 的服务器配置示例，您可以参考此配置添加到您的 MCP 客户端中：

{
   "snowflake-mcp-server": {  // 服务器名称，您可以自定义
      "command": "uv",  // 启动命令，这里使用 uv 包管理器
      "args": [
         "--directory",  // 参数，指定工作目录
         "/<path-to-code>/mcp-server-snowflake", // 替换为您的仓库代码的绝对路径
         "run",         // 参数，uv 的 run 命令
         "snowflake-mcp" // 参数，运行 snowflake-mcp 入口点
      ]
   }
}

配置说明:

'"snowflake-mcp-server"': 服务器的名称，在客户端中用于标识和选择该服务器。您可以自定义名称。
'"command": "uv"': 指定用于启动服务器的命令。这里假设您使用 'uv' 包管理器，并且 'uv' 命令在您的系统 PATH 环境变量中。如果 'uv' 不在 PATH 中，您需要提供 'uv' 的完整路径。
'"args"': 一个字符串数组，包含传递给 'uv' 命令的参数。
- '"--directory"': 指定服务器程序的工作目录，需要设置为您克隆的 'mcp-server-snowflake' 仓库的绝对路径。请将 '/<path-to-code>/mcp-server-snowflake' 替换为实际的仓库路径。
- '"run"': 告诉 'uv' 运行指定的 Python 入口点。
- '"snowflake-mcp"': 指定要运行的 Python 入口点名称。这个名称对应于 'pyproject.toml' 文件中 '[tool.uv.scripts]' 部分定义的 'snowflake-mcp = "mcp_server_snowflake.main:run_stdio_server"'。

查找 uv 路径: 如果您不确定 'uv' 的路径，可以在终端中运行 'which uv' 命令来查找。

基本使用方法

启动 MCP 服务器：按照上述服务器配置，在 MCP 客户端中添加并启动 "snowflake-mcp-server"。
在 LLM 客户端（如 Claude）中，您可以向其提问关于 Snowflake 数据库的问题，例如：
- "列出我 Snowflake 账户中的所有数据库"
- "列出 MARKETING 数据库中的所有视图"
- "描述 SALES 数据库中 CUSTOMER_ANALYTICS 视图的结构"
- "展示 FINANCE 数据库中 REVENUE_BY_REGION 视图的示例数据"
- "运行这个 SQL 查询：SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10"
- "查询 MARKETING 数据库，找出转化率最高的 5 个营销活动"
LLM 客户端会识别到可用的 Snowflake MCP 服务器，并根据您的提问，自动调用相应的工具来查询 Snowflake 数据库，并将结果返回给您。

注意: 所有查询操作都将在您配置的 Snowflake 账户和权限下执行，请确保服务帐户具有必要的只读权限。

关键词