Simple Snowflake MCP

🚀 简单雪花MCP服务器

简单雪花MCP服务器，可在企业代理后运行（因为我在几分钟内无法使用现有服务器实现此功能，但我自己的服务器可以）。目前仍不确定它是否出色，但就目前而言已经足够好了。

🚀 快速开始

安装

Claude桌面版

在MacOS上：~/Library/Application\ Support/Claude/claude_desktop_config.json 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "simple_snowflake_mcp": {
    "command": "uv",
    "args": [
      "--directory",
      ".", // 使用当前目录用于GitHub
      "run",
      "simple_snowflake_mcp"
    ]
  }
}

"mcpServers": {
  "simple_snowflake_mcp": {
    "command": "uvx",
    "args": [
      "simple_snowflake_mcp"
    ]
  }
}

✨ 主要特性

服务器公开了以下MCP工具以与雪花（Snowflake）进行交互：

• execute-snowflake-sql：在雪花上执行SQL查询并返回结果（字典列表）
• list-snowflake-warehouses：列出雪花上可用的数据仓库（DWH）
• list-databases：列出所有可访问的雪花数据库
• list-views：列出数据库和模式中的所有视图
• describe-view：提供视图的详细信息（列、SQL）
• query-view：查询视图，并可选择设置行限制（以Markdown格式返回结果）
• execute-query：以只读模式（SELECT、SHOW、DESCRIBE、EXPLAIN、WITH）或非只读模式（如果read_only为false）执行SQL查询，结果以Markdown格式返回

📦 安装指南

Docker设置

前提条件

• 系统已安装Docker和Docker Compose
• 拥有雪花的凭证

使用Docker快速启动

1. 克隆仓库

   git clone <your-repo>
   cd simple_snowflake_mcp
   

2. 设置环境变量

   cp .env.example .env
   # 使用你的雪花凭证编辑.env文件
   

3. 使用Docker Compose构建并运行

   # 构建Docker镜像
   docker-compose build
   
   # 启动服务
   docker-compose up -d
   
   # 查看日志
   docker-compose logs -f
   

Docker命令

使用Docker Compose直接操作：

# 构建镜像
docker-compose build

# 以生产模式启动
docker-compose up -d

# 以开发模式启动（挂载卷以实现实时代码更改）
docker-compose --profile dev up simple-snowflake-mcp-dev -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 清理（移除容器、镜像和卷）
docker-compose down --rmi all --volumes --remove-orphans

使用提供的Makefile（Windows用户可以通过WSL使用make或为Windows安装make）：

# 查看所有可用命令
make help

# 构建并启动
make build
make up

# 开发模式
make dev-up

# 查看日志
make logs

# 清理
make clean

Docker配置

Docker设置包括：

• Dockerfile：基于Python 3.11 slim基础镜像的多阶段构建
• docker-compose.yml：支持环境变量的服务定义
• .dockerignore：优化构建上下文
• Makefile：方便进行Docker操作的命令

环境变量

所有雪花配置都可以通过环境变量设置：

• SNOWFLAKE_USER：你的雪花用户名（必需）
• SNOWFLAKE_PASSWORD：你的雪花密码（必需）
• SNOWFLAKE_ACCOUNT：你的雪花账户标识符（必需）
• SNOWFLAKE_WAREHOUSE：仓库名称（可选）
• SNOWFLAKE_DATABASE：默认数据库（可选）
• SNOWFLAKE_SCHEMA：默认模式（可选）
• MCP_READ_ONLY：设置为"TRUE"以启用只读模式（默认：TRUE）

开发模式

对于开发，使用开发配置文件挂载源代码：

docker-compose --profile dev up simple-snowflake-mcp-dev -d

这允许你在不重建Docker镜像的情况下对代码进行更改。

💻 使用示例

基础用法

{
  "name": "execute-snowflake-sql",
  "arguments": { "sql": "SELECT CURRENT_TIMESTAMP;" }
}

调用MCP工具execute-snowflake-sql，并传入包含要执行的SQL查询的sql参数。结果将以字典列表的形式返回（每行一个字典）。

📚 详细文档

开发

构建和发布

为了准备软件包进行分发：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发版本：

uv build

这将在dist/目录中创建源代码和Wheel分发版本。

3. 发布到PyPI：

uv publish

注意：你需要通过环境变量或命令标志设置PyPI凭证：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器通过标准输入输出运行，调试可能具有挑战性。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过npm使用以下命令启动MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory . run simple-snowflake-mcp

启动后，Inspector将显示一个URL，你可以在浏览器中访问该URL以开始调试。

新特性：雪花SQL执行

服务器公开了一个MCP工具execute-snowflake-sql，用于在雪花上执行SQL查询并返回结果。

在VS Code中安装和配置

1. 克隆项目并安装依赖项

   git clone <your-repo>
   cd simple_snowflake_mcp
   python -m venv .venv
   .venv/Scripts/activate  # Windows
   pip install -r requirements.txt  # 或者如果可用，使用 `uv sync --dev --all-extras`
   

2. 配置雪花访问

   • 将.env.example复制到.env（或在根目录创建.env）并填写你的凭证：

     SNOWFLAKE_USER=...
     SNOWFLAKE_PASSWORD=...
     SNOWFLAKE_ACCOUNT=...
     # SNOWFLAKE_WAREHOUSE   可选：雪花仓库名称
     # SNOWFLAKE_DATABASE    可选：默认数据库名称
     # SNOWFLAKE_SCHEMA      可选：默认模式名称
     # MCP_READ_ONLY=true|false   可选：true/false以强制只读模式
     

3. 为MCP调试配置VS Code

   • .vscode/mcp.json文件已经存在：

     {
       "servers": {
         "simple-snowflake-mcp": {
           "type": "stdio",
           "command": ".venv/Scripts/python.exe",
           "args": ["-m", "simple_snowflake_mcp"]
         }
       }
     }
     

   • 打开命令面板（Ctrl+Shift+P），输入MCP: Start Server并选择simple-snowflake-mcp。

4. 使用方法

   • 公开的MCP工具允许你查询雪花（list-databases、list-views、describe-view、query-view、execute-query等）。
   • 更多示例，请参阅MCP协议文档：https://github.com/modelcontextprotocol/create-python-server

支持的MCP函数

服务器公开了以下MCP工具以与雪花进行交互：

• execute-snowflake-sql：在雪花上执行SQL查询并返回结果（字典列表）
• list-snowflake-warehouses：列出雪花上可用的数据仓库（DWH）
• list-databases：列出所有可访问的雪花数据库
• list-views：列出数据库和模式中的所有视图
• describe-view：提供视图的详细信息（列、SQL）
• query-view：查询视图，并可选择设置行限制（以Markdown格式返回结果）
• execute-query：以只读模式（SELECT、SHOW、DESCRIBE、EXPLAIN、WITH）或非只读模式（如果read_only为false）执行SQL查询，结果以Markdown格式返回

对于每个工具，请参阅使用部分或MCP文档以了解调用格式。