# Встановлення

> Встановіть StackQL на macOS, Linux, Windows, у Docker або хмарній оболонці й використовуйте сервер MCP StackQL у Claude Desktop, ChatGPT, Goose та інших клієнтах MCP або через npx, uvx, pip, Docker і GitHub Actions.

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

Тут наведено інструкції зі встановлення StackQL на різних платформах.

**macOS**

## macOS

StackQL доступний на macOS через Homebrew та інсталятор `pkg`; один багатоархітектурний інсталятор підтримує обидві архітектури: ARM (M1/Apple Silicon) і Intel (x86_64).

**Homebrew**

Для встановлення через Homebrew виконайте таку команду у вашому терміналі:

```bash
brew install stackql
```

**curl (підписаний і нотаризований двійковий файл)**

Щоб встановити підписаний і нотаризований виконуваний двійковий файл `stackql` у поточному каталозі, виконайте таку команду у вашому терміналі:

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

**Завантаження пакета**

StackQL доступний як підписаний і нотаризований інтерактивний інсталятор `pkg` для macOS.

[Завантажити PKG для macOS](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL доступний для всіх архітектур Linux.

**curl**

Щоб встановити виконуваний двійковий файл `stackql` для вашої архітектури Linux (amd64 або arm64) у поточному каталозі, виконайте таку команду у вашому терміналі:

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

**Завантаження пакета**

Або ж ви можете завантажити двійкові файли тут:

[Завантажити ZIP для Linux (amd64)](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[Завантажити ZIP для Linux (arm64)](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

StackQL доступний на Windows через Chocolatey, скрипт встановлення PowerShell та інсталятор MSI. Нативні збірки AMD64 (x64) і ARM64 доступні як інсталятори MSI та архіви ZIP, що містять `stackql.exe`. Збірка AMD64 також працює на ARM64 через емуляцію. Усі виконувані файли підписано сертифікатом підписування коду Authenticode.

**Chocolatey**

Для встановлення через Chocolatey виконайте таку команду у вашому терміналі PowerShell або `cmd`:

```powershell
choco install stackql
```

**Invoke-RestMethod**

Щоб встановити виконуваний файл із підписом Authenticode у поточному каталозі, виконайте таку команду в терміналі PowerShell: 

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

**Завантаження MSI/ZIP**

Завантажте нижче підписаний інсталятор або виконуваний файл `stackql` для Windows. Натискання кнопки завантаження за замовчуванням вибирає AMD64; скористайтеся її розкривним списком, щоб вибрати AMD64 або нативний ARM64.

[Завантажити MSI для Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[Завантажити ZIP для Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

Збірки StackQL публікуються в [Docker Hub](https://hub.docker.com/u/stackql).  

__Docker Hub__  

Щоб завантажити образ контейнера StackQL, виконайте таку команду:

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

Починаючи з `v1.0`, образ ґрунтується на Ubuntu 26.04 LTS, а варіант із попередньо встановленим Python 3.13 публікується із суфіксом тегу `-python3.13` (псевдонім `-python3`), наприклад:

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

**stackql-deploy**

## `stackql-deploy`

`stackql-deploy` - це фреймворк IaC без збереження стану, побудований на StackQL. Повну документацію див. у [__StackQL Deploy Docs__](https://stackql-deploy.io/).

__Linux / macOS__

Завантажує й розпаковує останній двійковий файл `stackql-deploy` за один крок. Інсталятор визначає вашу ОС та архітектуру (зокрема Apple Silicon та Intel через універсальний двійковий файл macOS) і автоматично отримує правильний файл випуску.
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

Завантажує й розпаковує останній двійковий файл `stackql-deploy` у поточний каталог.
Інсталятор визначає вашу платформу й автоматично отримує правильний файл випуску.
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

Якщо у вас встановлено набір інструментів Rust, ця команда збирає й встановлює двійковий файл безпосередньо з [__crates.io__](https://crates.io/crates/stackql-deploy).
```bash
cargo install stackql-deploy
```

**Хмарні оболонки**

## Хмарні оболонки

StackQL можна використовувати безпосередньо із вбудованих хмарних оболонок і вебтерміналів основних хмарних платформ і платформ даних. Це забезпечує безперешкодну роботу, оскільки ці середовища вже авторизовано з ідентичністю, під якою ви ввійшли, тож окремо налаштовувати автентифікацію не потрібно.

**AWS**

### AWS CloudShell

AWS CloudShell надає оболонку в браузері з попередньо встановленим і автентифікованим AWS CLI. Запуск StackQL в AWS CloudShell дає змогу виконувати запити до ресурсів AWS і керувати ними без додаткових кроків автентифікації. Докладні інструкції див. у нашому [посібнику з AWS CloudShell](/quick-starts/aws/aws-cloud-shell).

Спочатку завантажте пакет StackQL:

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
Потім запустіть скрипт StackQL для AWS CloudShell:

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

Цей скрипт запускає командну оболонку StackQL з вашими обліковими даними AWS CloudShell, тож ви можете одразу почати виконувати запити до ресурсів AWS.

**Azure**

### Azure Cloud Shell

Azure Cloud Shell надає доступне з браузера середовище оболонки, у якому Azure CLI вже автентифіковано вашим обліковим записом Azure. Використання StackQL в Azure Cloud Shell дає змогу безперешкодно виконувати запити до ваших ресурсів Azure без додаткового налаштування. Усі подробиці див. у нашому [посібнику з Azure Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell).  

Спочатку завантажте пакет StackQL:

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

Потім запустіть скрипт StackQL для Azure Cloud Shell:

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

Цей скрипт автоматично налаштовує сеанс StackQL на використання ваших облікових даних Azure Cloud Shell, тож ви можете одразу виконувати запити до ваших ресурсів Azure.

**Google**

### Google Cloud Shell

Google Cloud Shell пропонує середовище для розробки та експлуатації з уже автентифікованим Google Cloud CLI. Запуск StackQL у Google Cloud Shell дає змогу виконувати запити до ресурсів GCP з вашою наявною автентифікацією. Докладніше див. у нашому [посібнику з Google Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell).  

Спочатку завантажте пакет StackQL:

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

Потім запустіть скрипт StackQL для Google Cloud Shell:

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

Скрипт налаштовує StackQL на використання ваших облікових даних Google Cloud Shell, тож ви можете одразу почати виконувати запити до ваших ресурсів GCP за допомогою синтаксису SQL.

**Databricks**

### Вебтермінал Databricks

Робочі області Databricks містять вебтермінал, що працює від імені користувача, який увійшов у систему. Запуск StackQL у ньому дає змогу виконувати запити до вашої робочої області з вашою ідентичністю Databricks, без окремого налаштування автентифікації. Приклади запитів і автентифікацію на рівні облікового запису див. у нашому [посібнику з вебтерміналу Databricks](/blog/tutorials/stackql-in-databricks-web-terminal).

Спочатку завантажте пакет StackQL:

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

Потім запустіть скрипт оболонки StackQL для Databricks:

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

Так запускається сеанс StackQL з ідентичністю вашої робочої області Databricks, тож ви можете одразу виконувати запити до ресурсів на рівні робочої області, таких як `databricks_workspace.iam.vw_user_entitlements`. Для запитів на рівні облікового запису (створення ресурсів, виставлення рахунків, IAM облікового запису) встановіть змінні service principal OAuth2 для Databricks, як описано в посібнику.

## Використання з клієнтами MCP

Сервер MCP StackQL працює локально через stdio, тож облікові дані провайдерів залишаються на вашому комп'ютері, хоч би який клієнт ви використовували. Виберіть свій клієнт нижче: кожна вкладка спершу описує шлях через каталог або встановлення одним клацанням, а ручну конфігурацію наводить як резервний варіант. Усі канали розповсюдження, зокрема `npx`, Python, Docker і CI, див. у розділі [Встановлення сервера MCP](#installing-the-mcp-server).

**Claude Desktop**

### Claude Desktop

  Рекомендований спосіб встановити сервер MCP StackQL у Claude Desktop - з каталогу [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) (**Settings -> Connectors -> Add -> Browse Connectors**, знайдіть **StackQL**) - Claude Desktop автоматично вибирає правильний підписаний двійковий файл для вашої платформи.  Також до кожного випуску StackQL додано попередньо зібрані пакети MCP Bundle (`.mcpb`) для встановлення із завантаженого файлу - в обох випадках окремо встановлювати StackQL не потрібно.  Пакети доступні для macOS, Windows і Linux.

  Завантаження MCPB для Linux і Windows за замовчуванням використовують **amd64** (x64). Скористайтеся розкривними списками, щоб вибрати **amd64** або **arm64**.

  [Завантажити MCPB для macOS](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[Завантажити MCPB для Linux](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[Завантажити MCPB для Windows](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

Сервер MCP StackQL також зареєстровано в [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) як `io.github.stackql/stackql-mcp`.

:::

:::tip

Пакет - один із кількох способів запустити сервер MCP StackQL.  Повне покрокове керівництво для Claude Desktop див. на сторінці [__Використання StackQL із Claude Desktop__](/getting-started/claude-desktop), а варіанти з npx, Docker, Python, CI і ручним налаштуванням - у розділі [__Встановлення сервера MCP__](#installing-the-mcp-server).

:::

**ChatGPT**

### ChatGPT і Codex

  StackQL постачається як локальний плагін для настільного застосунку ChatGPT і Codex CLI. Плагін запускає сервер MCP StackQL через stdio на вашому комп'ютері, тож облікові дані провайдерів ніколи його не залишають. Потрібен Node.js 24.22.1 або новіший (22.23.4 чи 26.12.1 для відповідних гілок випусків); плагіну потрібні лише вбудовані модулі Node.js, він завантажує підписаний двійковий файл `stackql` під час першого використання та перевіряє його SHA-256.

  **Настільний застосунок ChatGPT (каталог плагінів):**  

  відкрийте каталог плагінів у настільному застосунку ChatGPT, знайдіть **StackQL** і натисніть **Install**, потім запустіть налаштування плагіна; skill `stackql-setup`, що входить до плагіна, допоможе налаштувати облікові дані й виконати перший запит. Сторінка в каталозі має позначку **Desktop only**: плагін встановлюється лише з настільного застосунку, а не з вебверсії чи мобільної версії ChatGPT, і його інструменти доступні в режимі Work, у threads, що виконуються на вашому комп'ютері. Якщо сторінки ще не видно у вашому каталозі, натомість встановіть плагін із маркетплейсу репозиторію.

  **Настільний застосунок ChatGPT (маркетплейс репозиторію):**  

  відкрийте **Settings -> Plugins -> Add -> Add from GitHub**, введіть `stackql/stackql`, потім встановіть **StackQL** з розділу **Personal** каталогу плагінів і перезапустіть застосунок.

  **Codex CLI:**

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

  Перезапустіть настільний застосунок ChatGPT або Codex, а потім спробуйте: *Використай StackQL, щоб за потреби встановити провайдер GitHub, а потім перелічи перші п'ять сервісів GitHub.* Облікові дані провайдерів зберігаються у файлі `~/.stackql/.env` під стандартними іменами змінних середовища кожного провайдера (наприклад, `AWS_ACCESS_KEY_ID` і `AWS_SECRET_ACCESS_KEY`); після редагування файлу попросіть агента викликати інструмент `reload_credentials`.

  **Без плагіна:**   

  у розділі **Settings -> Plugins -> MCPs -> Connect to a custom MCP** виберіть **STDIO**, укажіть команду `npx` і додайте аргументи `-y` та `@stackql/mcp-server`. Передайте облікові дані провайдерів як змінні середовища в цій формі.

:::note

Вебверсія та мобільна версія ChatGPT не можуть запускати локальний сервер stdio, тому плагін доступний лише для настільного застосунку та Codex. Відкрита помилка настільного застосунку ChatGPT ([openai/codex#38162](https://github.com/openai/codex/issues/38162)) може приховувати локальні інструменти MCP у сеансах **Chat**; на threads у режимі Work, threads Codex і Codex CLI вона не впливає.

:::

**Goose**

### Goose

  Goose запускає розширення stdio безпосередньо, тож вам потрібен лише засіб запуску `npx` (Node.js 24.22.1 або новіший, чи 22.23.4 або 26.12.1 для відповідних гілок випусків).

  **Goose Desktop:** натисніть кнопку нижче. Goose відкриється, покаже команду, яку збирається виконати, і попросить вас підтвердити її, а потім додасть StackQL як розширення.

  Встановити в Goose Desktop

  Кнопка - це глибоке посилання `goose://`; ви також можете вставити його в адресний рядок браузера або відкрити з термінала командою `open` (macOS), `start` (Windows) чи `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"
  ```

  або виконайте `goose configure`, виберіть **Add Extension -> Command-line Extension** і введіть ту саму команду. Коли з'явиться запит, укажіть облікові дані провайдерів як змінні середовища розширення.

:::note

Goose відмовився від власного каталогу розширень у застосунку на користь [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql), де StackQL зареєстровано як `io.github.stackql/stackql-mcp`. Щойно Goose випустить імпорт із реєстру, StackQL можна буде знайти там без жодних додаткових дій.

:::

## Встановлення сервера MCP

Сервер MCP StackQL дає змогу агентам ШІ виконувати запити до хмарних ресурсів і створювати їх за допомогою StackQL. Він постачається кількома каналами - усі вони запускають той самий сервер, тож виберіть канал, що відповідає вашому клієнту та вашим вимогам до довіри. Варіанти нижче наведено приблизно в порядку довіри та простоти.

### Маркетплейси й каталоги

Сервер опубліковано в Official MCP Registry як `io.github.stackql/stackql-mcp`; реєстри пакетів нижче містять артефакти для розповсюдження, а похідні каталоги беруть дані для своїх сторінок звідти.  

**Реєстри**

| Реєстр | Тип | Спосіб публікації | Сторінка | Примітки |
|---|---|---|---|---|
| Official MCP Registry | Канонічний реєстр метаданих | 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) | оголошує всі 8 пакетів (`mcpb x5`, `oci`, `npm`, `pypi`) |
| npm | Реєстр пакетів | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | засіб запуску `npx` |
| PyPI | Реєстр пакетів | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | засіб запуску `uvx` / `pip` |
| Docker Hub | Реєстр контейнерів | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | багатоархітектурний: `amd64` + `arm64` |
| GitHub Actions Marketplace | Маркетплейс CI (дія `setup-stackql-mcp`) | Публічний репозиторій + випуск + сторінка в маркетплейсі | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | Перевірений видавець; [`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**Каталоги**

Сторінки в каталогах і агрегаторах, приблизно в порядку значущості для пошуку:

| Каталог | Тип | Сторінка |
|---|---|---|
| __Anthropic Connector Directory__ | Каталог у застосунку Claude Desktop | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __OpenAI Plugin Directory__ | Каталог у настільному застосунку ChatGPT (лише настільна версія) | знайдіть **StackQL** у настільному застосунку ChatGPT; див. [ChatGPT і Codex](#using-with-mcp-clients) |
| __Cursor Directory__ | Каталог клієнтів IDE | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | Найбільший агрегатор | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | Пошук серверів; підтримує реєстр | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | Маркетплейс із пошуком | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | Агрегатор | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | Вебсайт у стилі awesome-list | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### Попередньо зібраний пакет `.mcpb`

**Коли використовувати:** Claude Desktop без доступу до Connector Directory або коли потрібно закріпити певну версію чи самостійно перевірити контрольні суми перед встановленням.  Для більшості користувачів Claude Desktop рекомендований спосіб встановлення - [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql).

До кожного випуску StackQL для кожної платформи додано попередньо зібраний пакет MCP Bundle:

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

де `<platform>` - одне зі значень `darwin-universal`, `windows-x64` (AMD64), `windows-arm64`, `linux-x64` або `linux-arm64`. Кнопки завантаження для кожної платформи розміщено на вкладці **Claude Desktop** у розділі [Використання з клієнтами MCP](#using-with-mcp-clients). Для кожного пакета на [сторінці випуску](https://github.com/stackql/stackql/releases/latest) є відповідна контрольна сума `.sha256`. Перевірте її, а потім встановіть пакет через **Settings -> Extensions** у Claude Desktop:

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

Повне покрокове керівництво див. на сторінці [Використання StackQL із Claude Desktop](/getting-started/claude-desktop#install-from-a-downloaded-bundle).

### Ручне налаштування `claude_desktop_config.json`

**Коли використовувати:** двійковий файл `stackql` уже є у вашому PATH, і ви використовуєте Claude Desktop або будь-який інший клієнт MCP, що працює через stdio.

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

Усі три аргументи обов'язкові:

- `--mcp.server.type=stdio` вибирає транспорт stdio, який використовують клієнти, вбудовані в редактори.
- `--approot` спрямовує кеш провайдерів у каталог, доступний для запису. Клієнти MCP можуть запускати сервер із робочим каталогом `/`, який недоступний для запису.
- `--mcp.config '{"server": {"audit": {"disabled": true}}}'` вимикає журнал аудиту, каталогом якого інакше за замовчуванням є робочий каталог (можливо, недоступний для запису).

Додайте облікові дані провайдерів у блоці `"env"` і налаштуйте контракт безпеки за допомогою `"mode"` - див. [Режими сервера](/command-line-usage/mcp#server-modes).

### `npx` (без встановлення)

**Коли використовувати:** будь-яке середовище Node, коли ви не хочете встановлювати StackQL глобально.

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

Засіб запуску [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) завантажує підписаний двійковий файл `stackql` під час першого запуску, перевіряє його SHA-256 і кешує для подальших запусків.

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

**Коли використовувати:** середовище Python - той самий засіб запуску, запакований для Python, що використовує спільний кеш двійкових файлів, який наповнює засіб запуску npx.

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

Або встановіть його в поточне середовище командою `pip install stackql-mcp-server` (Python 3.9+). На PyPI це пакет [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/).

### Docker

**Коли використовувати:** контейнеризоване або іншим чином ізольоване середовище виконання. Образ багатоархітектурний (amd64 і arm64).

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

Як конфігурація клієнта:

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

У Docker Hub це образ [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp).

### CI та агентні робочі процеси (GitHub Actions)

**Коли використовувати:** запуск сервера в завданні GitHub Actions, щоб агент міг виконувати запити до вашої хмари - і, якщо ви дозволите, виконувати в ній дії - у межах CI.

Дія [`stackql/setup-stackql-mcp@v1`](https://github.com/marketplace/actions/setup-stackql-mcp-server) встановлює двійковий файл і записує конфігурацію MCP (за замовчуванням у режимі `read_only`). Передайте цю конфігурацію в [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) через `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__*'
```

Більше агентних рецептів (аудит хмари, оцінювання витрат тощо) див. у [README дії](https://github.com/stackql/setup-stackql-mcp).

### Вбудований MCP

**Коли використовувати:** ви створюєте агентний застосунок і хочете включити сервер MCP у власний двійковий файл через вендоринг - без `npx`, без окремого встановлення, без залежності в середовищі виконання.

Нативні бібліотеки запускають підписаний двійковий файл `stackql` і працюють із ним через stdio за допомогою офіційного клієнта MCP SDK відповідної мови, тож ваш застосунок отримує той самий керований інтерфейс SQL до кожного провайдера в реєстрі. Кожна бібліотека за замовчуванням працює в режимі `read_only` - перехід до режиму із записом завжди явний - і може або завантажити й перевірити двійковий файл під час першого запуску, або включити його у вашу збірку через вендоринг, щоб отримати єдиний автономний виконуваний файл. Повний API для кожної мови наведено в [довіднику з вбудованого MCP](/mcp/embedded).

**Rust**

Crate `stackql-mcp` запускає двійковий файл і працює з ним через клієнт `rmcp`. Можливість `sidecar`, увімкнена за замовчуванням, завантажує й перевіряє двійковий файл під час першого запуску; можливість `vendored` вбудовує його за допомогою `include_bytes!`, щоб отримати єдиний автономний двійковий файл. 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?;
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-rs)
[Переглянути на crates.io](https://crates.io/crates/stackql-mcp)

Повний довідник: [Вбудований MCP: Rust](/mcp/embedded/rust).

**Go**

Бібліотека `stackql-mcp-go` запускає двійковий файл і працює з ним через офіційний клієнт MCP SDK для Go. Включіть двійковий файл через вендоринг за допомогою `go:embed`, щоб отримати єдиний автономний двійковий файл, або дозвольте бібліотеці завантажити й перевірити його під час першого запуску. За замовчуванням запускається в режимі `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()
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-go)
[Переглянути на pkg.go.dev](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

Повний довідник: [Вбудований MCP: Go](/mcp/embedded/go).

**Kotlin / JVM**

Бібліотека `io.stackql:stackql-mcp` запускає двійковий файл і працює з ним через офіційний клієнт MCP SDK для Kotlin, а супровідний плагін Gradle підключає той самий запуск до збірки. Потрібні JDK 17 і 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
}
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-kotlin)

Повний довідник: [Вбудований MCP: Kotlin / JVM](/mcp/embedded/kotlin).

**.NET**

Пакет `StackQL.Mcp` запускає двійковий файл і працює з ним через офіційний клієнт MCP SDK для C#. За замовчуванням працює як sidecar, або ж включіть пакет двійкового файлу через вендоринг як ресурс збірки, щоб отримати автономний виконуваний файл. Потрібен .NET 8 або новіший.

```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();
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-dotnet)

Повний довідник: [Вбудований MCP: .NET / C#](/mcp/embedded/dotnet).

**Gleam**

Бібліотека `stackql_mcp` орієнтована на середовище виконання Erlang/BEAM і надає сервер як дочірній процес OTP через `child_spec()`, тож його можна розмістити у вашому власному дереві супервізорів. За замовчуванням запускається в режимі `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)
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-gleam)

Повний довідник: [Вбудований MCP: Gleam](/mcp/embedded/gleam).

**Swift**

Пакет `stackql-mcp-swift` запускає двійковий файл і працює з ним через офіційний клієнт MCP SDK для Swift. Двійковий файл `darwin-universal` підписано Developer ID і нотаризовано Apple, тож ви можете включити його в підписаний застосунок `.app` і зберегти чинність нотаризації застосунку. Потрібні macOS 13+ і 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()
```

[Переглянути на GitHub](https://github.com/stackql/stackql-mcp-swift)

Повний довідник: [Вбудований MCP: Swift](/mcp/embedded/swift).

### Модель довіри

Ті самі властивості безпеки діють для кожного каналу:

- Вбудований двійковий файл `stackql` підписано Authenticode (Windows) і нотаризовано Apple (macOS).
- Кожен пакет `.mcpb` постачається з опублікованою контрольною сумою SHA-256 на сторінці випуску.
- Засоби запуску `npx` і `uvx` перевіряють SHA-256 завантаженого двійкового файлу перед першим використанням.
- Запис у [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) засвідчує хеші для кожної платформи.

## Використання GitHub Actions

[StackQL GitHub Actions](https://github.com/stackql/stackql-actions-demo) можна використовувати у ваших робочих процесах GitHub Actions. Доступні такі дії:

**stackql-deploy**

### `stackql-deploy`

Розгортайте або тестуйте стеки інфраструктури за допомогою StackQL безпосередньо з ваших робочих процесів GitHub. Ця дія уможливлює робочі процеси інфраструктури як коду (IaC) із синтаксисом, подібним до SQL, і дає змогу визначати й розгортати хмарні ресурси кількох провайдерів та керувати ними в одному робочому процесі.  

[Переглянути в GitHub Marketplace](https://github.com/marketplace/actions/stackql-deploy)
[Переглянути на GitHub](https://github.com/stackql/stackql-deploy-action)

__Приклад використання__

```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`

Налаштуйте StackQL у вашому робочому процесі GitHub Actions.  

[Переглянути в GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql)
[Переглянути на GitHub](https://github.com/stackql/setup-stackql)

__Приклад використання__

```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`

Встановіть сервер MCP StackQL у вашому робочому процесі GitHub Actions.  Дія встановлює підписаний двійковий файл і записує конфігурацію `mcpServers` (за замовчуванням у режимі `read_only`), яку агентний крок, наприклад `anthropics/claude-code-action`, отримує через `claude_args`.

[Переглянути в GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[Переглянути на GitHub](https://github.com/stackql/setup-stackql-mcp)

__Приклад використання__

```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`

Виконуйте команди StackQL у вашому робочому процесі GitHub Actions.  Запити можна передати безпосередньо або з файлу в репозиторії.  

[Переглянути в GitHub Marketplace](https://github.com/marketplace/actions/stackql-exec)
[Переглянути на GitHub](https://github.com/stackql/stackql-exec)

__Приклад використання__

```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`

Виконуйте модульні тести у вашому робочому процесі GitHub Actions (для перевірок забезпечення гарантій, керування чи безпеки хмари).  

[Переглянути в GitHub Marketplace](https://github.com/marketplace/actions/stackql-assert)
[Переглянути на GitHub](https://github.com/stackql/stackql-assert)

__Приклад використання__

```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 }}
```

## Інші бібліотеки

StackQL надає кілька способів інтеграції для використання в різних мовах програмування та середовищах. Ці бібліотеки розширюють функціональність StackQL і спрощують додавання запитів до хмарних ресурсів і керування ними у ваші наявні застосунки та робочі процеси.  

**pystackql**

### Пакет Python `pystackql`

Обгортка Python для використання StackQL у ваших програмах на Python. Пакет `pystackql` доступний на [__PyPI__](https://pypi.org/project/pystackql/), документація до пакета `pystackql` доступна на [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/). Щоб встановити пакет `pystackql`, виконайте таку команду:

```bash
pip install pystackql
```

У наведеному нижче прикладі пакет `pystackql` використовується разом із бібліотекою `pandas`, щоб виконувати запити StackQL і повертати результати в об'єкт `pandas.DataFrame`:

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

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

df = stackql.execute(query)
print(df)
```
