Simple Snowflake MCP

🚀 簡易Snowflake MCP服務器

這是一個簡易的Snowflake 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"
    ]
  }
}

📦 安裝指南

Docker設置

前提條件

• 系統上已安裝Docker和Docker Compose
• 擁有Snowflake憑證

使用Docker快速開始

1. 克隆倉庫

   git clone <your-repo>
   cd simple_snowflake_mcp
   

2. 設置環境變量

   cp .env.example .env
   # 使用你的Snowflake憑證編輯.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配置都可以通過環境變量設置：

• SNOWFLAKE_USER：你的Snowflake用戶名（必需）
• SNOWFLAKE_PASSWORD：你的Snowflake密碼（必需）
• SNOWFLAKE_ACCOUNT：你的Snowflake賬戶標識符（必需）
• SNOWFLAKE_WAREHOUSE：倉庫名稱（可選）
• SNOWFLAKE_DATABASE：默認數據庫（可選）
• SNOWFLAKE_SCHEMA：默認模式（可選）
• MCP_READ_ONLY：設置為 "TRUE" 以啟用只讀模式（默認：TRUE）

開發模式

對於開發，使用開發配置文件掛載你的源代碼：

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

這允許你在不重建Docker鏡像的情況下更改代碼。

💻 使用示例

新特性：Snowflake SQL執行

服務器提供了一個MCP工具 execute-snowflake-sql 來執行Snowflake上的SQL查詢並返回結果。

用法

調用MCP工具 execute-snowflake-sql 並傳入包含要執行的SQL查詢的 sql 參數。結果將作為字典列表返回（每行一個字典）。

示例：

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

結果將在MCP響應中返回。

在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. 配置Snowflake訪問

   • 將 .env.example 複製到 .env（或在根目錄創建 .env）並填寫你的憑證：

     SNOWFLAKE_USER=...
     SNOWFLAKE_PASSWORD=...
     SNOWFLAKE_ACCOUNT=...
     # SNOWFLAKE_WAREHOUSE   可選：Snowflake倉庫名稱
     # 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工具允許你查詢Snowflake（如 list-databases、list-views、describe-view、query-view、execute-query 等）。
   • 更多示例，請參閱MCP協議文檔：https://github.com/modelcontextprotocol/create-python-server

📚 詳細文檔

支持的MCP函數

服務器提供了以下MCP工具來與Snowflake進行交互：

• execute-snowflake-sql：在Snowflake上執行SQL查詢並返回結果（字典列表）
• list-snowflake-warehouses：列出Snowflake上可用的數據倉庫（DWH）
• list-databases：列出所有可訪問的Snowflake數據庫
• list-views：列出數據庫和模式中的所有視圖
• describe-view：提供視圖的詳細信息（列、SQL）
• query-view：查詢視圖並可選擇設置行限制（以Markdown格式返回結果）
• execute-query：以只讀模式（SELECT、SHOW、DESCRIBE、EXPLAIN、WITH）或非只讀模式（如果 read_only 為 false）執行SQL查詢，結果以Markdown格式返回

對於每個工具，請參閱用法部分或MCP文檔以瞭解調用格式。

開發

構建和發佈

為了準備包進行分發：

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以開始調試。