# Cài đặt

> Cài đặt StackQL trên macOS, Linux, Windows, Docker hoặc shell đám mây, và dùng máy chủ MCP StackQL từ Claude Desktop, ChatGPT, Goose và các ứng dụng khách MCP khác, hoặc qua npx, uvx, pip, Docker và GitHub Actions.

Source: https://stackql.io/vi/installing-stackql

Trang này cung cấp hướng dẫn cài đặt StackQL trên nhiều nền tảng khác nhau.

**macOS**

## macOS

StackQL khả dụng trên macOS qua Homebrew và trình cài đặt `pkg`; cả kiến trúc ARM (M1/Apple Silicon) và AMD đều được hỗ trợ bằng một trình cài đặt đa kiến trúc duy nhất.

**Homebrew**

Để cài đặt qua Homebrew, chạy lệnh sau trong terminal của bạn:

```bash
brew install stackql
```

**curl (tệp nhị phân được ký và công chứng)**

Để cài đặt tệp thực thi `stackql` được ký và công chứng vào thư mục hiện tại, chạy lệnh sau trong terminal của bạn:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Tải xuống gói**

StackQL khả dụng dưới dạng trình cài đặt `pkg` tương tác cho macOS, được ký và công chứng.

[Tải xuống PKG macOS](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL khả dụng cho mọi kiến trúc Linux.

**curl**

Để cài đặt tệp thực thi `stackql` cho kiến trúc Linux của bạn (amd64 hoặc arm64) vào thư mục hiện tại, chạy lệnh sau trong terminal của bạn:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Tải xuống gói**

Ngoài ra, bạn có thể tải xuống các tệp nhị phân tại đây:

[Tải xuống ZIP Linux (amd64)](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[Tải xuống ZIP Linux (arm64)](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

StackQL khả dụng trên Windows qua Chocolatey, tập lệnh cài đặt PowerShell và trình cài đặt MSI. Các bản dựng gốc AMD64 (x64) và ARM64 được cung cấp dưới dạng trình cài đặt MSI và tệp nén ZIP chứa `stackql.exe`. Bản dựng AMD64 cũng chạy được trên ARM64 thông qua mô phỏng. Mọi tệp thực thi đều được ký bằng chứng chỉ ký mã Authenticode.

**Chocolatey**

Để cài đặt qua Chocolatey, chạy lệnh sau trong terminal PowerShell hoặc `cmd` của bạn:

```powershell
choco install stackql
```

**Invoke-RestMethod**

Để cài đặt một tệp thực thi Authenticode vào thư mục hiện tại, chạy lệnh sau trong một terminal PowerShell: 

```powershell
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
```

**Tải xuống MSI/ZIP**

Tải xuống trình cài đặt hoặc tệp thực thi `stackql` được ký cho Windows bên dưới. Khi bạn nhấp vào một nút tải xuống, AMD64 được chọn theo mặc định; dùng danh sách thả xuống của nút để chọn AMD64 hoặc ARM64 gốc.

[Tải xuống MSI Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[Tải xuống ZIP Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

Các bản dựng StackQL được phát hành trên [Docker Hub](https://hub.docker.com/u/stackql).  

__Docker Hub__  

Để tải xuống image container StackQL, chạy lệnh sau:

```bash
docker pull stackql/stackql
```

Từ `v1.0`, image dựa trên Ubuntu 26.04 LTS, và một biến thể đã cài đặt sẵn Python 3.13 được phát hành với hậu tố tag `-python3.13` (bí danh `-python3`), ví dụ:

```bash
docker pull stackql/stackql:latest-python3.13
```

**stackql-deploy**

## `stackql-deploy`

`stackql-deploy` là một framework IaC phi trạng thái dựa trên StackQL. Để biết tài liệu đầy đủ, hãy xem [__Tài liệu StackQL Deploy__](https://stackql-deploy.io/).

__Linux / macOS__

Tải xuống và giải nén tệp nhị phân `stackql-deploy` mới nhất trong một bước. Trình cài đặt phát hiện hệ điều hành và kiến trúc của bạn (bao gồm Apple Silicon và Intel qua một tệp nhị phân macOS universal) và tự động tải tệp phát hành phù hợp.
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

Tải xuống và giải nén tệp nhị phân `stackql-deploy` mới nhất vào thư mục hiện tại.
Trình cài đặt phát hiện nền tảng của bạn và tự động tải tệp phát hành phù hợp.
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

Nếu bạn đã cài đặt toolchain Rust, lệnh này dựng và cài đặt tệp nhị phân trực tiếp từ [__crates.io__](https://crates.io/crates/stackql-deploy).
```bash
cargo install stackql-deploy
```

**Shell đám mây**

## Shell đám mây

Bạn có thể dùng StackQL trực tiếp từ shell đám mây và terminal web tích hợp sẵn của các nền tảng đám mây và nền tảng dữ liệu chính. Cách này mang lại trải nghiệm liền mạch vì các môi trường này đã được ủy quyền sẵn bằng danh tính mà bạn đang đăng nhập, nên bạn không cần cấu hình xác thực riêng.

**AWS**

### AWS CloudShell

AWS CloudShell cung cấp một shell chạy trên trình duyệt, với AWS CLI đã được cài đặt và xác thực sẵn. Khi chạy StackQL trong AWS CloudShell, bạn có thể truy vấn và quản lý tài nguyên AWS mà không cần thêm bước xác thực nào. Để biết các bước chi tiết, hãy xem [hướng dẫn AWS CloudShell](/quick-starts/aws/aws-cloud-shell) của chúng tôi.

Trước tiên, tải xuống gói StackQL:

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
Sau đó, chạy tập lệnh StackQL cho AWS CloudShell:

```bash
./stackql-aws-cloud-shell.sh
```  

Tập lệnh này khởi động shell lệnh StackQL bằng thông tin xác thực AWS CloudShell của bạn, cho phép bạn bắt đầu truy vấn tài nguyên AWS ngay lập tức.

**Azure**

### Azure Cloud Shell

Azure Cloud Shell cung cấp một môi trường shell truy cập được từ trình duyệt, với Azure CLI đã được xác thực sẵn bằng tài khoản Azure của bạn. Khi dùng StackQL trong Azure Cloud Shell, bạn có thể truy vấn tài nguyên Azure một cách liền mạch mà không cần cấu hình thêm. Để biết đầy đủ chi tiết, hãy xem [hướng dẫn Azure Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell) của chúng tôi.  

Trước tiên, tải xuống gói StackQL:

```bash
curl -fsSL https://get-stackql.io/install/azure | sh
```

Sau đó, chạy tập lệnh StackQL cho Azure Cloud Shell:

```bash
./stackql-azure-cloud-shell.sh
```

Tập lệnh này tự động cấu hình một phiên StackQL để dùng thông tin xác thực Azure Cloud Shell của bạn, giúp bạn truy vấn tài nguyên Azure ngay lập tức.

**Google**

### Google Cloud Shell

Google Cloud Shell cung cấp một môi trường phát triển và vận hành với Google Cloud CLI đã được xác thực sẵn. Khi chạy StackQL trong Google Cloud Shell, bạn có thể truy vấn tài nguyên GCP bằng xác thực hiện có của mình. Tìm hiểu thêm trong [hướng dẫn Google Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell) của chúng tôi.  

Trước tiên, tải xuống gói StackQL:

```bash
curl -fsSL https://get-stackql.io/install/google | sh
```

Sau đó, chạy tập lệnh StackQL cho Google Cloud Shell:

```bash
./stackql-google-cloud-shell.sh
```

Tập lệnh này cấu hình StackQL để dùng thông tin xác thực Google Cloud Shell của bạn, cho phép bạn bắt đầu truy vấn tài nguyên GCP ngay lập tức bằng cú pháp SQL.

**Databricks**

### Databricks Web Terminal

Không gian làm việc Databricks có một terminal web chạy dưới danh nghĩa người dùng đang đăng nhập. Khi chạy StackQL tại đó, bạn có thể truy vấn không gian làm việc bằng danh tính Databricks của mình mà không cần cấu hình xác thực riêng. Để biết các truy vấn ví dụ và cách xác thực ở cấp tài khoản, hãy xem [hướng dẫn Databricks Web Terminal](/blog/tutorials/stackql-in-databricks-web-terminal) của chúng tôi.

Trước tiên, tải xuống gói StackQL:

```bash
curl -fsSL https://get-stackql.io/install/databricks | sh
```

Sau đó, chạy tập lệnh shell StackQL cho Databricks:

```bash
./stackql-databricks-shell.sh
```

Lệnh này khởi động một phiên StackQL bằng danh tính không gian làm việc Databricks của bạn, nhờ đó bạn có thể truy vấn ngay các tài nguyên trong phạm vi không gian làm việc, chẳng hạn như `databricks_workspace.iam.vw_user_entitlements`. Đối với truy vấn ở cấp tài khoản (cấp phát, thanh toán, IAM tài khoản), hãy đặt các biến service principal OAuth2 của Databricks như mô tả trong hướng dẫn.

## Sử dụng với ứng dụng khách MCP

Máy chủ MCP StackQL chạy cục bộ qua stdio, nên thông tin xác thực provider luôn nằm trên máy của bạn, dù bạn dùng ứng dụng khách nào. Chọn ứng dụng khách của bạn bên dưới: mỗi tab trình bày trước cách cài đặt qua thư mục hoặc bằng một cú nhấp, sau đó là cấu hình thủ công làm fallback. Để biết mọi kênh phân phối, bao gồm `npx`, Python, Docker và CI, hãy xem [Cài đặt máy chủ MCP](#installing-the-mcp-server).

**Claude Desktop**

### Claude Desktop

  Cách được khuyên dùng để cài đặt máy chủ MCP StackQL vào Claude Desktop là từ [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) (**Settings -> Connectors -> Add -> Browse Connectors**, tìm **StackQL**) - Claude Desktop tự động chọn đúng tệp nhị phân được ký cho nền tảng của bạn.  Ngoài ra, các MCP Bundle (`.mcpb`) dựng sẵn được đính kèm vào mọi bản phát hành StackQL để cài đặt từ tệp đã tải xuống - dù theo cách nào, bạn cũng không cần cài đặt StackQL riêng.  Bundle khả dụng cho macOS, Windows và Linux.

  Bản tải xuống MCPB cho Linux và Windows mặc định là **amd64** (x64). Dùng danh sách thả xuống để chọn **amd64** hoặc **arm64**.

  [Tải xuống MCPB macOS](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[Tải xuống MCPB Linux](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[Tải xuống MCPB Windows](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

Máy chủ MCP StackQL cũng được liệt kê trên [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) với tên `io.github.stackql/stackql-mcp`.

:::

:::tip

Bundle là một trong nhiều cách để chạy máy chủ MCP StackQL.  Xem [__Sử dụng StackQL với Claude Desktop__](/getting-started/claude-desktop) để biết hướng dẫn đầy đủ cho Claude Desktop, hoặc [__Cài đặt máy chủ MCP__](#installing-the-mcp-server) để biết các tùy chọn npx, Docker, Python, CI và thủ công.

:::

**ChatGPT**

### ChatGPT và Codex

  StackQL được phát hành dưới dạng plugin cục bộ cho ứng dụng ChatGPT trên máy tính và Codex CLI. Plugin chạy máy chủ MCP StackQL qua stdio trên máy của bạn, nên thông tin xác thực provider không bao giờ rời khỏi máy. Yêu cầu Node.js 24.22.1 trở lên (22.23.4 hoặc 26.12.1 trên các dòng phát hành đó); plugin chỉ cần các mô-đun tích hợp sẵn của Node.js, tải xuống tệp nhị phân `stackql` được ký trong lần sử dụng đầu tiên và xác minh SHA-256 của tệp.

  **Ứng dụng ChatGPT trên máy tính (thư mục plugin):**  

  mở thư mục plugin trong ứng dụng ChatGPT trên máy tính, tìm **StackQL** và nhấp **Install**, sau đó chạy phần thiết lập của plugin; skill `stackql-setup` đi kèm sẽ hướng dẫn bạn qua thông tin xác thực và truy vấn đầu tiên. Mục này có huy hiệu **Desktop only**: plugin chỉ cài đặt được từ ứng dụng trên máy tính, không cài đặt được từ ChatGPT web hoặc di động, và các công cụ của plugin khả dụng trong chế độ Work, trong các thread chạy trên máy tính của bạn. Nếu mục này chưa hiển thị trong thư mục của bạn, hãy cài đặt từ marketplace của kho lưu trữ.

  **Ứng dụng ChatGPT trên máy tính (marketplace của kho lưu trữ):**  

  mở **Settings -> Plugins -> Add -> Add from GitHub**, nhập `stackql/stackql`, sau đó cài đặt **StackQL** từ phần **Personal** của thư mục plugin và khởi động lại ứng dụng.

  **Codex CLI:**

  ```shell
  codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
  codex plugin add stackql@stackql
  ```

  Khởi động lại ChatGPT trên máy tính hoặc Codex, sau đó thử: *Dùng StackQL để cài đặt provider GitHub nếu cần, sau đó liệt kê năm dịch vụ GitHub đầu tiên.* Thông tin xác thực provider được đặt trong `~/.stackql/.env` theo tên biến môi trường chuẩn của từng provider (ví dụ `AWS_ACCESS_KEY_ID` và `AWS_SECRET_ACCESS_KEY`); sau khi sửa tệp, hãy yêu cầu tác nhân gọi `reload_credentials`.

  **Không dùng plugin:**   

  trong **Settings -> Plugins -> MCPs -> Connect to a custom MCP**, chọn **STDIO**, đặt lệnh là `npx` và thêm các đối số `-y` và `@stackql/mcp-server`. Cung cấp thông tin xác thực provider dưới dạng biến môi trường trên biểu mẫu đó.

:::note

ChatGPT web và di động không thể chạy máy chủ stdio cục bộ, nên plugin chỉ dùng được trên máy tính và Codex. Một lỗi đang mở của ChatGPT trên máy tính ([openai/codex#38162](https://github.com/openai/codex/issues/38162)) có thể ẩn các công cụ MCP cục bộ khỏi các phiên **Chat**; các thread ở chế độ Work, thread Codex và Codex CLI không bị ảnh hưởng.

:::

**Goose**

### Goose

  Goose chạy trực tiếp các tiện ích mở rộng stdio, nên bạn chỉ cần trình khởi chạy `npx` (Node.js 18 trở lên).

  **Goose Desktop:** nhấp vào nút bên dưới. Goose mở ra, hiển thị lệnh sắp chạy và yêu cầu bạn xác nhận, sau đó thêm StackQL làm tiện ích mở rộng.

  Cài đặt trong Goose Desktop

  Nút này là một liên kết sâu `goose://`; bạn cũng có thể dán nó vào thanh địa chỉ của trình duyệt, hoặc mở nó từ terminal bằng `open` (macOS), `start` (Windows) hoặc `xdg-open` (Linux):

  ```
  goose://extension?cmd=npx&arg=-y&arg=%40stackql%2Fmcp-server&id=stackql&name=StackQL&description=Query%20and%20provision%20cloud%20and%20SaaS%20resources%20with%20SQL
  ```

  **Goose CLI:**

  ```shell
  goose session --with-extension "npx -y @stackql/mcp-server"
  ```

  hoặc chạy `goose configure`, chọn **Add Extension -> Command-line Extension** và nhập cùng lệnh đó. Cung cấp thông tin xác thực provider dưới dạng biến môi trường của tiện ích mở rộng khi được yêu cầu.

:::note

Goose đã ngừng dùng thư mục tiện ích mở rộng trong ứng dụng để chuyển sang [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql), nơi StackQL được liệt kê với tên `io.github.stackql/stackql-mcp`. Khi Goose phát hành tính năng nhập từ registry, StackQL sẽ có thể được tìm thấy ở đó mà không cần thao tác gì thêm.

:::

## Cài đặt máy chủ MCP

Máy chủ MCP StackQL cho phép tác nhân AI truy vấn và cấp phát tài nguyên đám mây bằng StackQL. Máy chủ được phân phối qua nhiều kênh - tất cả đều chạy cùng một máy chủ, vì vậy hãy chọn kênh phù hợp với ứng dụng khách và yêu cầu tin cậy của bạn. Các tùy chọn bên dưới được sắp xếp gần đúng theo mức độ tin cậy và mức độ dễ dùng.

### Marketplace và thư mục

Máy chủ được phát hành lên Official MCP Registry với tên `io.github.stackql/stackql-mcp`; các registry gói bên dưới chứa các artifact để phân phối, và các thư mục ở hạ nguồn lấy mục từ đó.  

**Registry**

| Registry | Loại | Phát hành qua | Mục | Ghi chú |
|---|---|---|---|---|
| Official MCP Registry | Registry siêu dữ liệu chuẩn | CLI `mcp-publisher` + `server.json` | [`modelcontextprotocol.io/search`](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) [`modelcontextprotocol.io/direct`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.stackql/stackql-mcp) | công bố cả 8 gói (`mcpb x5`, `oci`, `npm`, `pypi`) |
| npm | Registry gói | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | trình khởi chạy `npx` |
| PyPI | Registry gói | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | trình khởi chạy `uvx` / `pip` |
| Docker Hub | Registry container | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | đa kiến trúc `amd64` + `arm64` |
| GitHub Actions Marketplace | Marketplace CI (action `setup-stackql-mcp`) | Kho lưu trữ công khai + bản phát hành + mục marketplace | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | Nhà phát hành đã xác minh; [`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**Thư mục**

Các mục trên thư mục và trang tổng hợp, sắp xếp gần đúng theo mức độ quan trọng đối với khả năng được tìm thấy:

| Thư mục | Loại | Mục |
|---|---|---|
| __Anthropic Connector Directory__ | Thư mục trong ứng dụng Claude Desktop | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __OpenAI Plugin Directory__ | Thư mục trong ứng dụng ChatGPT trên máy tính (chỉ trên máy tính) | tìm **StackQL** trong ứng dụng ChatGPT trên máy tính; xem [ChatGPT và Codex](#using-with-mcp-clients) |
| __Cursor Directory__ | Thư mục ứng dụng khách IDE | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | Trang tổng hợp lớn nhất | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | Khám phá, đơn vị hỗ trợ registry | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | Marketplace có thể tìm kiếm | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | Trang tổng hợp | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | Trang awesome-list | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### Bundle `.mcpb` dựng sẵn

**Khi nào nên dùng:** Claude Desktop không có quyền truy cập Connector Directory, hoặc khi bạn muốn ghim một phiên bản cụ thể hoặc tự xác minh checksum trước khi cài đặt.  Với hầu hết người dùng Claude Desktop, [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) là cách cài đặt được khuyên dùng.

Mỗi bản phát hành StackQL đều đính kèm một MCP Bundle dựng sẵn cho từng nền tảng:

```
https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb
```

trong đó `<platform>` là một trong các giá trị `darwin-universal`, `windows-x64` (AMD64), `windows-arm64`, `linux-x64` hoặc `linux-arm64`. Các nút tải xuống cho từng nền tảng nằm trong tab **Claude Desktop** ở phần [Sử dụng với ứng dụng khách MCP](#using-with-mcp-clients). Mỗi bundle có một checksum `.sha256` tương ứng trên [trang phát hành](https://github.com/stackql/stackql/releases/latest). Xác minh checksum, sau đó cài đặt qua **Settings -> Extensions** trong Claude Desktop:

```bash
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
```

Xem [Sử dụng StackQL với Claude Desktop](/getting-started/claude-desktop#install-from-a-downloaded-bundle) để biết hướng dẫn từng bước đầy đủ.

### Cấu hình `claude_desktop_config.json` thủ công

**Khi nào nên dùng:** bạn đã có tệp nhị phân `stackql` trong PATH và dùng Claude Desktop hoặc bất kỳ ứng dụng khách MCP stdio nào khác.

```json
{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--approot", "/Users/you/.stackql",
        "--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
      ]
    }
  }
}
```

Cả ba đối số đều không thể thiếu:

- `--mcp.server.type=stdio` chọn phương thức truyền tải stdio mà các ứng dụng khách nhúng trong trình soạn thảo sử dụng.
- `--approot` trỏ cache provider đến một thư mục có thể ghi. Ứng dụng khách MCP có thể khởi chạy máy chủ với thư mục làm việc là `/`, vốn không thể ghi.
- `--mcp.config '{"server": {"audit": {"disabled": true}}}'` tắt nhật ký kiểm tra; nếu không tắt, nhật ký này mặc định dùng thư mục làm việc (có thể không ghi được) làm thư mục của nó.

Thêm thông tin xác thực provider bằng khối `"env"` và điều chỉnh hợp đồng an toàn bằng `"mode"` - xem [Chế độ máy chủ](/command-line-usage/mcp#server-modes).

### `npx` (không cần cài đặt)

**Khi nào nên dùng:** mọi môi trường Node, khi bạn không muốn cài đặt StackQL toàn cục.

```json
{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }
```

Trình khởi chạy [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) tải xuống tệp nhị phân `stackql` được ký trong lần chạy đầu tiên, xác minh SHA-256 của tệp và lưu tệp vào cache cho các lần chạy sau.

### `uvx` / `pip` (Python)

**Khi nào nên dùng:** môi trường Python - cùng trình khởi chạy đó được đóng gói cho Python, dùng chung cache tệp nhị phân mà trình khởi chạy npx tạo ra.

```json
{ "mcpServers": { "stackql": { "command": "uvx", "args": ["stackql-mcp-server"] } } }
```

Hoặc cài đặt vào môi trường hiện tại bằng `pip install stackql-mcp-server` (Python 3.9+). Gói này có tên [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) trên PyPI.

### Docker

**Khi nào nên dùng:** runtime chạy trong container hoặc được cô lập theo cách khác. Image hỗ trợ đa kiến trúc (amd64 và arm64).

```bash
docker run -i --rm stackql/stackql-mcp
```

Dưới dạng cấu hình ứng dụng khách:

```json
{ "mcpServers": { "stackql": { "command": "docker", "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] } } }
```

Image này có tên [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) trên Docker Hub.

### CI và quy trình làm việc dựa trên tác nhân (GitHub Actions)

**Khi nào nên dùng:** chạy máy chủ bên trong một job GitHub Actions để tác nhân có thể truy vấn - và, nếu bạn cho phép, thao tác trên - môi trường đám mây của bạn như một phần của CI.

[`stackql/setup-stackql-mcp@v1`](https://github.com/marketplace/actions/setup-stackql-mcp-server) cài đặt tệp nhị phân và ghi một cấu hình MCP (mặc định ở chế độ `read_only`). Truyền cấu hình đó cho [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) qua `claude_args`:

```yaml
- id: stackql
  uses: stackql/setup-stackql-mcp@v1
  with:
    auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Using stackql, list the public repositories in the stackql org and
      summarise them as a markdown table.
    claude_args: |
      --mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
      --allowedTools 'mcp__stackql__*'
```

Xem [README của action](https://github.com/stackql/setup-stackql-mcp) để biết thêm các công thức dựa trên tác nhân (kiểm tra đám mây, ước tính chi phí, v.v.).

### MCP nhúng

**Khi nào nên dùng:** bạn đang xây dựng một ứng dụng dựa trên tác nhân và muốn đưa máy chủ MCP vào tệp nhị phân của mình theo kiểu vendoring - không cần `npx`, không cần cài đặt riêng, không có phần phụ thuộc runtime.

Các thư viện gốc khởi chạy tệp nhị phân `stackql` được ký qua stdio, phía sau ứng dụng khách SDK MCP chính thức của từng ngôn ngữ, nhờ đó ứng dụng của bạn có cùng một giao diện SQL được quản trị đến mọi provider trong registry. Mỗi thư viện mặc định dùng `read_only` - việc nâng lên chế độ có quyền ghi luôn phải được chỉ định rõ ràng - và có thể tải xuống rồi xác minh tệp nhị phân trong lần chạy đầu tiên, hoặc đưa nó vào bản dựng của bạn theo kiểu vendoring để có một tệp thực thi độc lập duy nhất. API đầy đủ cho từng ngôn ngữ có trong [tài liệu tham khảo MCP nhúng](/mcp/embedded).

**Rust**

Crate `stackql-mcp` khởi chạy tệp nhị phân phía sau một ứng dụng khách `rmcp`. Tính năng mặc định `sidecar` tải xuống và xác minh tệp nhị phân trong lần chạy đầu tiên; tính năng `vendored` nhúng tệp nhị phân bằng `include_bytes!` để có một tệp nhị phân độc lập duy nhất. MSRV Rust 1.88.

```toml
# Cargo.toml
stackql-mcp = "0.1"
```

```rust
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
    .mode(Mode::ReadOnly)
    .start()
    .await?;
let tools = server.list_all_tools().await?;
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-rs)
[Xem trên crates.io](https://crates.io/crates/stackql-mcp)

Tài liệu tham khảo đầy đủ: [MCP nhúng: Rust](/mcp/embedded/rust).

**Go**

Thư viện `stackql-mcp-go` khởi chạy tệp nhị phân phía sau ứng dụng khách SDK MCP chính thức cho Go. Đưa tệp nhị phân vào theo kiểu vendoring bằng `go:embed` để có một tệp nhị phân độc lập duy nhất, hoặc để thư viện tải xuống và xác minh tệp trong lần chạy đầu tiên. Theo mặc định, thư viện khởi động ở chế độ `read_only`.

```bash
go get github.com/stackql/stackql-mcp-go
```

```go
import (
    "context"
    stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)

client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
    Binary: StackqlMCPBinary(),
})
defer client.Close()
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-go)
[Xem trên pkg.go.dev](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

Tài liệu tham khảo đầy đủ: [MCP nhúng: Go](/mcp/embedded/go).

**Kotlin / JVM**

Thư viện `io.stackql:stackql-mcp` khởi chạy tệp nhị phân phía sau ứng dụng khách SDK MCP chính thức cho Kotlin, và một plugin Gradle đi kèm tích hợp cùng cách khởi chạy đó vào bản dựng. Yêu cầu JDK 17 và Kotlin 2.x.

```kotlin
dependencies {
    implementation("io.stackql:stackql-mcp:0.1.0")
}
```

```kotlin
import io.stackql.mcp.Mode
import io.stackql.mcp.StackqlMcp

val server = StackqlMcp.builder().mode(Mode.ReadOnly).start()
server.use {
    val tools = server.client.listTools().tools
}
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-kotlin)

Tài liệu tham khảo đầy đủ: [MCP nhúng: Kotlin / JVM](/mcp/embedded/kotlin).

**.NET**

Gói `StackQL.Mcp` khởi chạy tệp nhị phân phía sau ứng dụng khách SDK MCP chính thức cho C#. Theo mặc định dùng sidecar, hoặc đưa bundle vào theo kiểu vendoring dưới dạng tài nguyên bản dựng để có một tệp thực thi độc lập. Yêu cầu .NET 8 trở lên.

```bash
dotnet add package StackQL.Mcp
```

```csharp
using StackQL.Mcp;

await using var server = await StackqlMcp.CreateBuilder()
    .WithMode(StackqlMode.ReadOnly)
    .StartAsync();

var tools = await server.ListToolsAsync();
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-dotnet)

Tài liệu tham khảo đầy đủ: [MCP nhúng: .NET / C#](/mcp/embedded/dotnet).

**Gleam**

Thư viện `stackql_mcp` nhắm đến runtime Erlang/BEAM và cung cấp máy chủ dưới dạng một tiến trình con OTP qua `child_spec()`, nhờ đó máy chủ có thể nằm trong supervision tree của riêng bạn. Theo mặc định, thư viện khởi động ở chế độ `read_only`.

```bash
gleam add stackql_mcp
```

```gleam
import envoy
import stackql_mcp

let assert Ok(server) =
  stackql_mcp.start(
    config: stackql_mcp.default_config(),
    home: "/home/u", os: "linux", arch: "x86_64",
    getenv: envoy.get,
  )
let assert Ok(tools) = stackql_mcp.list_tools(server)
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-gleam)

Tài liệu tham khảo đầy đủ: [MCP nhúng: Gleam](/mcp/embedded/gleam).

**Swift**

Gói `stackql-mcp-swift` khởi chạy tệp nhị phân phía sau ứng dụng khách SDK MCP chính thức cho Swift. Tệp nhị phân `darwin-universal` được ký bằng Developer ID và được Apple công chứng, nên bạn có thể đóng gói nó bên trong một `.app` được ký mà vẫn giữ hiệu lực công chứng của ứng dụng. Yêu cầu macOS 13+ và Swift 6.1 (Xcode 16.3+).

```swift
// Package.swift
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")
```

```swift
import StackQLMCP

var options = Options()
options.mode = .readOnly

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
await server.stop()
```

[Xem trên GitHub](https://github.com/stackql/stackql-mcp-swift)

Tài liệu tham khảo đầy đủ: [MCP nhúng: Swift](/mcp/embedded/swift).

### Mô hình tin cậy

Các thuộc tính bảo mật sau áp dụng như nhau cho mọi kênh:

- Tệp nhị phân `stackql` nhúng được ký bằng Authenticode (Windows) và được Apple công chứng (macOS).
- Mỗi bundle `.mcpb` đều đi kèm một checksum SHA-256 được đăng trên trang phát hành.
- Trình khởi chạy `npx` và `uvx` xác minh SHA-256 của tệp nhị phân đã tải xuống trước lần sử dụng đầu tiên.
- Mục trên [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) xác nhận hash của từng nền tảng.

## Sử dụng GitHub Actions

Bạn có thể dùng [GitHub Actions StackQL](https://github.com/stackql/stackql-actions-demo) trong các workflow GitHub Actions của mình. Hiện có các action sau:

**stackql-deploy**

### `stackql-deploy`

Triển khai hoặc kiểm thử các stack hạ tầng bằng StackQL trực tiếp từ các workflow GitHub của bạn. Action này hỗ trợ các workflow hạ tầng dưới dạng mã (IaC) bằng cú pháp giống SQL, giúp bạn định nghĩa, triển khai và quản lý tài nguyên đám mây trên nhiều provider trong một workflow duy nhất.  

[Xem trên GitHub Marketplace](https://github.com/marketplace/actions/stackql-deploy)
[Xem trên GitHub](https://github.com/stackql/stackql-deploy-action)

__Ví dụ sử dụng__

```yaml
...
jobs:
  stackql-actions-test:
    name: StackQL Actions Test
    runs-on: ubuntu-latest
    env:
      GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Deploy a Stack
        uses: stackql/stackql-deploy-action@v2
        with:
          command: 'build'
          stack_dir: 'examples/k8s-the-hard-way'
          stack_env: 'dev'
          env_vars: |
            GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo
            GOOGLE_REGION=australia-southeast1
```

**setup-stackql**

### `setup-stackql`

Thiết lập StackQL trong workflow GitHub Actions của bạn.  

[Xem trên GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql)
[Xem trên GitHub](https://github.com/stackql/setup-stackql)

__Ví dụ sử dụng__

```yaml
- name: setup StackQL
  uses: stackql/setup-stackql@v2
  with:
    use_wrapper: true

- name: Use GitHub Provider
  run: |
    stackql exec -i ./examples/github-example.iql
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}
```

**setup-stackql-mcp**

### `setup-stackql-mcp`

Cài đặt máy chủ MCP StackQL trong workflow GitHub Actions của bạn.  Action này cài đặt tệp nhị phân được ký và ghi một cấu hình `mcpServers` (mặc định ở chế độ `read_only`) mà một bước dựa trên tác nhân như `anthropics/claude-code-action` sử dụng qua `claude_args`.

[Xem trên GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[Xem trên GitHub](https://github.com/stackql/setup-stackql-mcp)

__Ví dụ sử dụng__

```yaml
- id: stackql
  uses: stackql/setup-stackql-mcp@v1
  with:
    auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Using stackql, list the public repositories in the stackql org and
      summarise them as a markdown table.
    claude_args: |
      --mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
      --allowedTools 'mcp__stackql__*'
```

**stackql-exec**

### `stackql-exec`

Thực thi các lệnh StackQL trong workflow GitHub Actions của bạn.  Truy vấn có thể được viết trực tiếp hoặc lấy từ một tệp trong kho lưu trữ.  

[Xem trên GitHub Marketplace](https://github.com/marketplace/actions/stackql-exec)
[Xem trên GitHub](https://github.com/stackql/stackql-exec)

__Ví dụ sử dụng__

```yaml
- name: exec github example
  uses: stackql/stackql-exec@v2
  with:
    query: |
      select total_private_repos
      from github.orgs.orgs
      where org = 'stackql'
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}
```

**stackql-assert**

### `stackql-assert`

Thực hiện kiểm thử đơn vị trong workflow GitHub Actions của bạn (cho các bước kiểm tra đảm bảo, quản trị hoặc bảo mật đám mây).  

[Xem trên GitHub Marketplace](https://github.com/marketplace/actions/stackql-assert)
[Xem trên GitHub](https://github.com/stackql/stackql-assert)

__Ví dụ sử dụng__

```yaml
- name: Use test query string and expected rows
  uses: stackql/stackql-assert@v2
  with:
    test_query: |
        SELECT name
        FROM google.compute.instances 
        WHERE project = 'stackql-demo' AND zone = 'australia-southeast1-a' AND name = 'stackql-demo-001';
    expected_rows: 1
  env: 
    GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
```

## Các thư viện khác

StackQL cung cấp nhiều cách tích hợp để dùng trong các ngôn ngữ lập trình và môi trường khác nhau. Các thư viện này mở rộng các tính năng của StackQL, giúp bạn dễ dàng đưa việc truy vấn và quản lý tài nguyên đám mây vào các ứng dụng và workflow hiện có.  

**pystackql**

### Gói Python `pystackql`

Wrapper Python để dùng StackQL trong các chương trình Python của bạn. Gói `pystackql` có trên [__PyPI__](https://pypi.org/project/pystackql/), tài liệu cho gói `pystackql` có trên [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/). Để cài đặt gói `pystackql`, chạy lệnh sau:

```bash
pip install pystackql
```

Ví dụ sau cho thấy gói `pystackql` được dùng cùng `pandas` để chạy truy vấn StackQL và trả kết quả về một `pandas.DataFrame`:

```python
from pystackql import StackQL
import pandas as pd
region = "ap-southeast-2"
stackql = StackQL()

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

res = stackql.execute(query)
df = pd.read_json(res)
print(df)
```
