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文檔以瞭解調用格式。