本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。
在 Claude Desktop 中使用 StackQL
StackQL 透過 Model Context Protocol(MCP)與 Claude Desktop 整合,讓您能以自然語言查詢及佈建跨多個雲端服務供應商的雲端資源。這個強大的組合讓您能以對話方式與雲端基礎架構互動,同時在底層運用 StackQL 以 SQL 為基礎的介面。
共有三種安裝選項,以下依建議順序說明:從 Anthropic Connector Directory 安裝、從下載的安裝套件安裝,或手動註冊本機安裝的 StackQL 二進位檔。
從 Connector Directory 安裝(建議)
在 Claude Desktop 中使用 StackQL MCP 伺服器最簡單的方式,是從 Anthropic Connector Directory 安裝。在 Claude Desktop 中前往 Settings -> Connectors -> Add -> Browse Connectors,搜尋 StackQL,然後按一下 Install。不需要下載任何檔案,也不需要另外安裝 StackQL。

您也可以直接在 claude.ai/directory 檢視此上架頁面。
這會以 in-process 方式為您的平台安裝 StackQL MCP 伺服器:上架頁面提供一個合併的多平台安裝套件,內含適用於 macOS universal、Windows x64 以及 Linux x64 和 arm64 的已簽署二進位檔,Claude Desktop 會自動為您的電腦選取正確的版本。若是原生 Windows ARM64,請從下方的下載項目安裝另外提供的 windows-arm64 安裝套件。Windows 二進位檔經過 Authenticode 簽署,macOS 二進位檔經過 Apple 公證,與獨立的 StackQL 發行版本使用相同的二進位檔。

從目錄安裝的 connector 會繼承 Claude Desktop 的環境,因此請在啟動 Claude Desktop 之前,於作業系統層級設定 Provider 所需的環境變數(請參閱各 Provider 專屬憑證)。Claude Desktop 會在啟動時擷取其環境:變更變數後,您必須完全結束 Claude Desktop(在 Windows 上包括系統匣圖示)並重新啟動。要求代理程式執行 reload_credentials 會回報每個 Provider 的憑證狀態,這是確認伺服器能看到與看不到哪些內容最快的方式。
Claude Desktop 會宣告 MCP 徵詢(elicitation)功能,因此預設的伺服器模式(safe)會在每次變更時要求您核准(請參閱伺服器模式)。
從下載的安裝套件安裝
若要固定特定版本、在無法存取 Connector Directory 的情況下安裝,或在安裝前自行驗證總和檢查碼,請使用此安裝選項。
預先建置的 MCP Bundle(.mcpb)是可一鍵安裝的套件,內含已簽署的 stackql 二進位檔與伺服器設定。不需要另外安裝 StackQL。
從最新的發行版本下載適用於您平台的安裝套件:
| 平台 | 安裝套件 |
|---|---|
| macOS (universal) | stackql-mcp-darwin-universal.mcpb |
| Windows AMD64 (x64) | stackql-mcp-windows-x64.mcpb |
| Windows ARM64(原生) | stackql-mcp-windows-arm64.mcpb |
| Linux x64 | stackql-mcp-linux-x64.mcpb |
| Linux arm64 | stackql-mcp-linux-arm64.mcpb |
接著在 Claude Desktop 中前往 Settings -> Extensions -> Install Extension,然後選取下載的檔案。內嵌的二進位檔經過 Authenticode 簽署(Windows)及 Apple 公證(macOS);在發行版本頁面上,每個安裝套件旁都附有 .sha256 總和檢查碼。若要在安裝前驗證:
# macOS / Linux
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
此伺服器也以 io.github.stackql/stackql-mcp 的名稱列於 Official MCP Registry,該登錄庫固定了這些總和檢查碼。
手動設定
如果您已安裝 StackQL,可以直接在 Claude Desktop 的設定檔中註冊 StackQL MCP 伺服器。
必要條件
在 Claude Desktop 中設定 StackQL 之前,請確認您已具備:
- 已安裝 StackQL:從 stackql.io 下載並安裝 StackQL,或使用套件管理員
- Claude Desktop:從 Anthropic 網站 下載
- 雲端服務供應商憑證:您要使用之雲端服務供應商的 API 金鑰或憑證
執行下列命令,確認 StackQL 位於系統 PATH 中:
stackql --version
設定 MCP 伺服器
若要讓 Claude Desktop 與 StackQL 通訊,您需要在 Claude Desktop 設定檔中設定 MCP 伺服器。
Windows
編輯位於下列位置的設定檔:
%APPDATA%\Claude\claude_desktop_config.json
macOS
編輯位於下列位置的設定檔:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux
編輯位於下列位置的設定檔:
~/.config/Claude/claude_desktop_config.json
設定範例
將下列設定新增至您的 claude_desktop_config.json 檔案:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure"
],
"env": {
"GOOGLE_CREDENTIALS": "/path/to/google-credentials.json",
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
"AZURE_CLIENT_ID": "your-azure-client-id",
"AZURE_CLIENT_SECRET": "your-azure-client-secret",
"AZURE_TENANT_ID": "your-azure-tenant-id",
"DATABRICKS_CLIENT_ID": "your-databricks-client-id",
"DATABRICKS_CLIENT_SECRET": "your-databricks-client-secret",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
您只需要包含您打算使用之雲端服務供應商的環境變數。請從設定中移除任何未使用的 Provider 憑證。
絕對不要將含有實際憑證的 claude_desktop_config.json 檔案提交至版本控制。請採用安全的憑證管理做法。
Claude Desktop 會宣告 MCP 徵詢功能,因此預設的伺服器模式(safe)會在每次變更時要求您核准。若只需資源清單的存取權限,請切換為 mode: read_only;若要略過核准要求,請切換為 mode: full_access(請參閱伺服器模式)。
使用憑證檔案(--env.file)
除了 env 區塊之外,另一種做法(在 Windows 上也是建議的做法)是將憑證存放在 dotenv 格式的檔案中,並以 --env.file 旗標傳入:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure",
"--env.file=C:\\Users\\me\\stackql-credentials.env"
]
}
}
}
搭配一個最精簡的憑證檔案:
# stackql-credentials.env
GOOGLE_CREDENTIALS=/path/to/google-credentials.json
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
這種做法優於 env 區塊的原因:
- 變更
env區塊後,必須完全重新啟動 Claude Desktop(包括結束系統匣圖示),MCP 子處理程序才會看到變更;而在 Windows 上,setx寫入的是登錄庫,永遠不會傳達到正在執行的 Desktop 處理程序。 --env.file檔案可以隨時建立或輪替,伺服器啟動時甚至不需要存在;只要要求代理程式執行reload_credentials,即可在不重新啟動的情況下套用變更。
--env.file 和 reload_credentials 適用於 v0.10.542 之後的 StackQL 發行版本。
各 Provider 專屬憑證
不同的雲端服務供應商需要不同的驗證方法,請參閱 Provider 文件(https://stackql.io/providers),了解您所需 Provider 要求的環境變數。
重新啟動 Claude Desktop
更新設定檔後,請重新啟動 Claude Desktop 以載入新的 MCP 伺服器設定。當您開始新的對話時,StackQL MCP 伺服器會自動啟動。
您可以做什麼
設定完成後,您可以在 Claude Desktop 中使用自然語言:
查詢雲端資源
要求 Claude 擷取雲端基礎架構的相關資訊:
- 「顯示我在 us-central1 區域中所有的 GCP 運算執行個體」
- 「列出我 AWS 帳戶中所有的 S3 儲存貯體」
- 「我的訂用帳戶中有哪些 Azure 虛擬機器正在執行?」
- 「顯示 default 命名空間中所有的 Kubernetes Pod」
佈建資源
使用對話式命令建立及部署雲端資源:
- 「在 us-west-2 中建立名為『my-data-bucket』的 S3 儲存貯體」
- 「部署一個啟用版本控制的 GCP Cloud Storage 儲存貯體」
- 「在 us-east-1 中啟動一個小型 EC2 執行個體」
- 「在 westus2 中建立 Azure 資源群組」
分析與稽核
執行安全性稽核與合規性檢查:
- 「顯示所有可公開存取的 S3 儲存貯體」
- 「列出 90 天未登入的 IAM 使用者」
- 「找出所有未正確加上標籤的 GCP 執行個體」
- 「找出未啟用備份的 Azure VM」
跨雲端作業
查詢及比較多個雲端服務供應商的資源:
- 「顯示 AWS、GCP 和 Azure 中所有的運算執行個體」
- 「比較 AWS S3 與 GCP Cloud Storage 的儲存成本」
- 「列出所有雲端服務供應商中的所有資料庫」
基礎架構即程式碼
產生並執行基礎架構部署查詢:
- 「建立一個包含 VPC、子網路和 EC2 執行個體的資源堆疊」
- 「部署一個含節點集區的完整 GKE 叢集」
- 「在 AWS 中設定多區域部署」
修改資源
更新現有的雲端資源:
- 「為所有未加上標籤的 EC2 執行個體新增標籤」
- 「為 S3 儲存貯體『my-bucket』啟用加密」
- 「更新 GCP 執行個體『web-server-1』的機器類型」
- 「將我的 Cloud Storage 儲存貯體的 ACL 變更為私人」
刪除資源
移除不再需要的雲端資源:
- 「刪除 S3 儲存貯體『temp-bucket』」
- 「移除所有已停止的 EC2 執行個體」
- 「清除未使用的 GCP 磁碟」
對話範例
以下範例說明您可以如何透過 StackQL 與 Claude Desktop 互動:
您:「可以顯示我所有的 GCP 運算執行個體嗎?」
Claude:執行 StackQL 查詢,並以格式化表格傳回結果,顯示執行個體名稱、可用區域、機器類型和狀態
您:「在 us-central1 區域中建立一個名為『analytics-data-2025』的新 Cloud Storage 儲存貯體,並使用統一儲存貯體層級存取權」
Claude:執行 StackQL INSERT 陳述式以建立儲存貯體,並確認建立完成
您:「現在列出我所有的 Cloud Storage 儲存貯體」
Claude:執行 SELECT 查詢,並顯示所有儲存貯體,包括剛建立的那一個
提示與最佳做法
-
具體明確:您的要求越具體,得到的結果就越好。請盡可能包含資源名稱、區域和具體屬性。
-
使用自然語言:您不需要了解 SQL 語法,Claude 會將您的自然語言要求轉譯為 StackQL 查詢。
-
執行前先檢閱:對於破壞性作業(DELETE、UPDATE),Claude 通常會在繼續之前向您顯示將要執行的內容。
-
多步驟作業:您可以在單一對話中串連多項作業。Claude 會在整個工作階段中維持上下文。
-
錯誤處理:如果查詢失敗,Claude 可以協助進行疑難排解,並根據錯誤訊息建議修正方式。
-
探索功能:詢問 Claude「我可以用 StackQL 做什麼?」,以取得針對您已設定之 Provider 的建議。
疑難排解
MCP 伺服器無法啟動
如果 Claude Desktop 無法連線到 StackQL MCP 伺服器:
- 確認 StackQL 位於您的 PATH 中
- 檢查您的
claude_desktop_config.json檔案是否為有效的 JSON - 確認設定中的檔案路徑對您的作業系統而言是正確的
- 檢閱 Claude Desktop 記錄中的錯誤訊息
驗證錯誤
如果您收到驗證錯誤:
- 確認您的雲端服務供應商憑證正確無誤
- 確認憑證檔案存在於指定的路徑
- 檢查設定中的環境變數格式是否正確;要求代理程式執行
reload_credentials會回報每個 Provider 的憑證狀態,這是查看缺少哪個變數最快的方式 - 確認您的憑證具有必要的權限
權限錯誤
如果作業因權限不足而失敗:
- 確認您的服務帳戶或 IAM 使用者具有必要的權限
- 檢查 Provider 專屬的 IAM 政策
- 確認已在您的雲端專案中啟用 API 服務
深入了解
安全性考量
- 安全地儲存憑證,絕對不要將其提交至版本控制
- 對服務帳戶採用最低權限存取原則
- 定期輪替憑證與 API 金鑰
- 監控 MCP 伺服器記錄中的異常活動
- 考慮使用雲端服務供應商的憑證管理工具(例如 Secret Manager、Parameter Store)