金大哥 - simple_snowflake

article

README

🚀 简单雪花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快速启动

克隆仓库

git clone <your-repo>
cd simple_snowflake_mcp

设置环境变量

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

使用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中安装和配置

克隆项目并安装依赖项

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`

配置雪花访问

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

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

为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。

使用方法
- 提供的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文档。

🔧 技术细节

构建和发布

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

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

uv sync

构建软件包分发：

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 参数，结果将以字典列表（每行一个字典）的形式返回。

simple_snowflake_mcp