Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.
Використання StackQL із Claude Desktop
StackQL інтегрується з Claude Desktop через Model Context Protocol (MCP), що дає змогу виконувати запити до хмарних ресурсів і створювати їх у кількох постачальників хмарних послуг природною мовою. Це потужне поєднання дає змогу взаємодіяти з вашою хмарною інфраструктурою у формі розмови, а за лаштунками працює інтерфейс StackQL на основі SQL.
Є три варіанти встановлення, наведені тут у рекомендованому порядку: встановлення з Anthropic Connector Directory, встановлення із завантаженого пакета або ручна реєстрація локально встановленого двійкового файлу StackQL.
Встановлення з Connector Directory (рекомендовано)
Найпростіший спосіб використовувати сервер MCP StackQL із Claude Desktop - встановити його з Anthropic Connector Directory. У Claude Desktop виберіть Settings -> Connectors -> Add -> Browse Connectors, знайдіть StackQL і натисніть Install. Нічого завантажувати не потрібно, і окреме встановлення StackQL теж не потрібне.

Сторінку в каталозі також можна переглянути безпосередньо за адресою claude.ai/directory.
Так встановлюється внутрішньопроцесний сервер MCP StackQL для вашої платформи: сторінка в каталозі надає комбінований багатоплатформний пакет із підписаними двійковими файлами для macOS universal, Windows x64, а також Linux x64 і arm64, і Claude Desktop автоматично вибирає потрібний для вашої машини. Для нативної Windows ARM64 встановіть окремий пакет windows-arm64 з завантажень нижче. Двійкові файли для Windows підписано Authenticode, а двійковий файл для macOS нотаризовано Apple - це ті самі двійкові файли, що й в автономному випуску StackQL.

Конектор, встановлений із каталогу, успадковує середовище Claude Desktop, тому встановіть змінні середовища для ваших провайдерів на рівні операційної системи до запуску Claude Desktop - див. Облікові дані для окремих провайдерів. Claude Desktop фіксує своє середовище під час запуску: після змінення змінних потрібно повністю закрити Claude Desktop (зокрема значок у системному лотку у Windows) і запустити його знову. Якщо попросити агента запустити reload_credentials, він повідомить стан облікових даних для кожного провайдера; це найшвидший спосіб перевірити, що сервер бачить, а чого ні.
Claude Desktop оголошує можливість elicitation протоколу MCP, тому режим сервера за замовчуванням (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
Сервер також є в офіційному реєстрі MCP під назвою io.github.stackql/stackql-mcp, і цей реєстр закріплює ці контрольні суми.
Ручна конфігурація
Якщо StackQL уже встановлено, можна зареєструвати сервер MCP StackQL безпосередньо у файлі конфігурації Claude Desktop.
Передумови
Перш ніж налаштовувати StackQL для роботи з Claude Desktop, переконайтеся, що у вас є:
- Встановлений StackQL - завантажте та встановіть StackQL з stackql.io або скористайтеся менеджером пакетів
- Claude Desktop - завантажте з вебсайту Anthropic
- Облікові дані постачальників хмарних послуг - ключі API або облікові дані для постачальників хмарних послуг, з якими ви плануєте працювати
Переконайтеся, що StackQL є у вашому системному PATH, виконавши команду:
stackql --version
Налаштування сервера MCP
Щоб Claude Desktop міг взаємодіяти з StackQL, потрібно налаштувати сервер MCP у файлі конфігурації Claude Desktop.
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"
],
"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"
}
}
}
}
Потрібно додавати лише змінні середовища для постачальників хмарних послуг, які ви плануєте використовувати. Видаліть із конфігурації облікові дані провайдерів, які не використовуються.
Ніколи не додавайте файл claude_desktop_config.json зі справжніми обліковими даними до системи контролю версій. Дотримуйтеся безпечних практик керування обліковими даними.
Claude Desktop оголошує можливість elicitation протоколу 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",
"--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:
- Щоб дочірній процес MCP побачив зміни в блоці
env, потрібно повністю перезапустити Claude Desktop (зокрема закрити значок у системному лотку), а у Windowssetxзаписує в реєстр, і ці зміни ніколи не доходять до запущеного процесу Desktop. - Файл
--env.fileможна створити або ротувати будь-коли (він навіть не мусить існувати під час запуску сервера), а якщо попросити агента запуститиreload_credentials, зміни буде підхоплено без жодного перезапуску.
--env.file і reload_credentials доступні у випусках StackQL після v0.10.542.
Облікові дані для окремих провайдерів
Різні постачальники хмарних послуг потребують різних способів автентифікації; змінні середовища, потрібні для вибраних провайдерів, див. у документації провайдерів (https://stackql.io/providers).
Перезапуск Claude Desktop
Після оновлення файлу конфігурації перезапустіть Claude Desktop, щоб завантажити нову конфігурацію сервера MCP. Сервер MCP StackQL запуститься автоматично, коли ви почнете нову розмову.
Що можна робити
Після налаштування можна використовувати природну мову в Claude Desktop, щоб:
Виконання запитів до хмарних ресурсів
Попросіть Claude отримати інформацію про вашу хмарну інфраструктуру:
- "Покажи всі мої обчислювальні екземпляри GCP у регіоні us-central1"
- "Перелічи всі бакети S3 у моєму обліковому записі AWS"
- "Які віртуальні машини Azure працюють у моїй підписці?"
- "Покажи всі поди Kubernetes у просторі імен default"
Створення ресурсів
Створюйте та розгортайте хмарні ресурси за допомогою розмовних команд:
- "Створи бакет S3 з назвою 'my-data-bucket' у us-west-2"
- "Розгорни бакет GCP Cloud Storage з увімкненим керуванням версіями"
- "Запусти невеликий екземпляр EC2 в us-east-1"
- "Створи групу ресурсів Azure у westus2"
Аналіз і аудит
Виконуйте аудити безпеки й перевірки відповідності вимогам:
- "Покажи всі загальнодоступні бакети S3"
- "Перелічи користувачів IAM, які не входили в систему 90 днів"
- "Знайди всі екземпляри GCP без належних міток"
- "Визнач віртуальні машини Azure без увімкненого резервного копіювання"
Операції в кількох хмарах
Виконуйте запити до ресурсів і порівнюйте їх у кількох постачальників хмарних послуг:
- "Покажи всі обчислювальні екземпляри в AWS, GCP і Azure"
- "Порівняй вартість зберігання в AWS S3 і GCP Cloud Storage"
- "Перелічи всі бази даних у всіх постачальників хмарних послуг"
Інфраструктура як код
Генеруйте та виконуйте запити для розгортання інфраструктури:
- "Створи стек ресурсів, що містить VPC, підмережу й екземпляр EC2"
- "Розгорни повний кластер GKE з пулами вузлів"
- "Налаштуй розгортання в кількох регіонах AWS"
Змінення ресурсів
Оновлюйте наявні хмарні ресурси:
- "Додай теги до всіх екземплярів EC2 без тегів"
- "Увімкни шифрування для бакета S3 'my-bucket'"
- "Онови тип машини екземпляра GCP 'web-server-1'"
- "Зміни ACL мого бакета Cloud Storage на приватний"
Видалення ресурсів
Видаляйте хмарні ресурси, коли вони більше не потрібні:
- "Видали бакет S3 'temp-bucket'"
- "Видали всі зупинені екземпляри EC2"
- "Прибери невикористовувані диски GCP"
Приклад розмови
Ось приклад того, як можна взаємодіяти з Claude Desktop за допомогою StackQL:
Ви: "Можеш показати всі мої обчислювальні екземпляри GCP?"
Claude: Виконує запит StackQL і повертає результати у відформатованій таблиці з назвами екземплярів, зонами, типами машин і станом
Ви: "Створи новий бакет Cloud Storage з назвою 'analytics-data-2025' у регіоні us-central1 з уніфікованим доступом на рівні бакета"
Claude: Виконує інструкцію INSERT у StackQL, щоб створити бакет, і підтверджує створення
Ви: "Тепер перелічи всі мої бакети Cloud Storage"
Claude: Виконує запит SELECT і показує всі бакети, зокрема щойно створений
Поради й найкращі практики
-
Будьте конкретними: що конкретніше прохання, то кращі результати ви отримаєте. За можливості вказуйте назви ресурсів, регіони й конкретні атрибути.
-
Використовуйте природну мову: знати синтаксис SQL не потрібно - Claude перетворює ваші прохання природною мовою на запити StackQL.
-
Переглядайте перед виконанням: для деструктивних операцій (DELETE, UPDATE) Claude зазвичай показує, що буде виконано, перш ніж продовжити.
-
Багатокрокові операції: в одній розмові можна об'єднувати операції в ланцюжок. Claude зберігає контекст протягом усього сеансу.
-
Обробка помилок: якщо запит завершується помилкою, Claude може допомогти усунути несправність і запропонувати виправлення на основі повідомлення про помилку.
-
Досліджуйте можливості: запитайте Claude "Що я можу робити зі StackQL?", щоб отримати пропозиції для ваших налаштованих провайдерів.
Усунення несправностей
Сервер MCP не запускається
Якщо Claude Desktop не може підключитися до сервера MCP StackQL:
- Переконайтеся, що StackQL є у вашому PATH
- Перевірте, що файл
claude_desktop_config.jsonмістить допустимий JSON - Переконайтеся, що шлях до файлу в конфігурації правильний для вашої операційної системи
- Перегляньте журнали Claude Desktop на наявність повідомлень про помилки
Помилки автентифікації
Якщо ви отримуєте помилки автентифікації:
- Переконайтеся, що облікові дані постачальника хмарних послуг правильні
- Переконайтеся, що файли облікових даних існують за вказаними шляхами
- Перевірте, що змінні середовища в конфігурації правильно відформатовано - якщо попросити агента запустити
reload_credentials, він повідомить стан облікових даних для кожного провайдера; це найшвидший спосіб з'ясувати, якої змінної бракує - Переконайтеся, що ваші облікові дані мають потрібні дозволи
Помилки дозволів
Якщо операції завершуються помилкою через недостатні дозволи:
- Переконайтеся, що ваш обліковий запис служби або користувач IAM має потрібні дозволи
- Перевірте політики IAM конкретного провайдера
- Переконайтеся, що сервіси API увімкнено у ваших хмарних проєктах
Докладніше
- Довідник із команди MCP у StackQL
- StackQL Provider Registry
- Специфікація мови
- Документація Model Context Protocol
Міркування щодо безпеки
- Зберігайте облікові дані в безпечному місці й ніколи не додавайте їх до системи контролю версій
- Застосовуйте принцип мінімальних привілеїв для облікових записів служб
- Регулярно виконуйте ротацію облікових даних і ключів API
- Відстежуйте в журналах сервера MCP незвичну активність
- Розгляньте можливість використання засобів керування обліковими даними постачальників хмарних послуг (наприклад, Secret Manager, Parameter Store)