Simple Snowflake MCP

🚀 简单雪花MCP服务器

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

🚀 快速开始

✨ 主要特性

服务器提供了以下与雪花（Snowflake）交互的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格式呈现

📦 安装指南

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

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镜像的情况下修改代码。

在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

💻 使用示例

基础用法

以下是调用 execute-snowflake-sql 工具执行SQL查询的示例：

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

结果将在MCP响应中返回。

📚 详细文档

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

🔧 技术细节

构建和发布

要准备分发软件包，请执行以下步骤：

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

uv sync

2. 构建软件包分发：

uv build

这将在 dist/ 目录中创建源和轮子分发。 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查询并返回结果。使用时，调用 execute-snowflake-sql 工具并传入包含要执行的SQL查询的 sql 参数，结果将以字典列表（每行一个字典）的形式返回。