# インストール

> StackQL を macOS、Linux、Windows、Docker、クラウドシェルにインストールし、Claude Desktop、ChatGPT、Goose などの MCP クライアントや npx、uvx、pip、Docker、GitHub Actions から StackQL MCP サーバーを使用します。

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

このページでは、さまざまなプラットフォームに StackQL をインストールする手順を説明します。

**macOS**

## macOS

StackQL は macOS で Homebrew と `pkg` インストーラーから利用できます。ARM（M1/Apple Silicon）と AMD の両アーキテクチャが、単一のマルチアーキテクチャインストーラーでサポートされています。

**Homebrew**

Homebrew でインストールするには、ターミナルで次のコマンドを実行します。

```bash
brew install stackql
```

**curl（署名済みかつ公証済みのバイナリ）**

署名済みかつ公証済みの `stackql` 実行可能バイナリをカレントディレクトリにインストールするには、ターミナルで次のコマンドを実行します。

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

**パッケージのダウンロード**

StackQL は、macOS 向けの署名済みかつ公証済みの対話型 `pkg` インストーラーとして利用できます。

[macOS PKG をダウンロード](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL はすべての Linux アーキテクチャで利用できます。

**curl**

使用している Linux アーキテクチャ（amd64 または arm64）用の `stackql` 実行可能バイナリをカレントディレクトリにインストールするには、ターミナルで次のコマンドを実行します。

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

**パッケージのダウンロード**

または、ここからバイナリをダウンロードできます。

[Linux ZIP（amd64）をダウンロード](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[Linux ZIP（arm64）をダウンロード](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

StackQL は Windows で Chocolatey、PowerShell インストールスクリプト、MSI インストーラーから利用できます。ネイティブの AMD64（x64）ビルドと ARM64 ビルドが、MSI インストーラーと、`stackql.exe` を含む ZIP アーカイブとして提供されています。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 のダウンロード**

署名済みの Windows 用 `stackql` インストーラーまたは実行ファイルを以下からダウンロードします。ダウンロードボタンをクリックすると、デフォルトで AMD64 が選択されます。AMD64 とネイティブ ARM64 のどちらかを選ぶには、ボタンのドロップダウンを使用します。

[Windows MSI をダウンロード](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[Windows ZIP をダウンロード](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

StackQL のビルドは [DockerHub](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` は、StackQL 上に構築されたステートレスな IaC フレームワークです。完全なドキュメントについては、[__StackQL Deploy ドキュメント__](https://stackql-deploy.io/)を参照してください。

__Linux / macOS__

最新の `stackql-deploy` バイナリを 1 回の手順でダウンロードして展開します。インストーラーは OS とアーキテクチャ（ユニバーサル macOS バイナリによる Apple Silicon と Intel を含む）を検出し、適切なリリースアセットを自動的に取得します。
```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 は、主要なクラウドプラットフォームとデータプラットフォームに組み込まれたクラウドシェルや Web ターミナルから直接使用できます。これらの環境はログイン中の ID で事前に認可されているため、個別に認証を設定する必要がなく、シームレスに使用できます。

**AWS**

### AWS Cloud Shell

AWS CloudShell は、AWS CLI がプリインストールされ認証済みの、ブラウザーベースのシェルを提供します。AWS CloudShell で StackQL を実行すると、追加の認証手順なしで 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
```  

このスクリプトは AWS CloudShell の認証情報を使用して StackQL のコマンドシェルを起動するため、すぐに AWS リソースのクエリを開始できます。

**Azure**

### Azure Cloud Shell

Azure Cloud Shell は、Azure CLI が Azure アカウントで事前に認証された、ブラウザーからアクセスできるシェル環境を提供します。Azure Cloud Shell で StackQL を使用すると、追加の設定なしで 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
```

このスクリプトは Azure Cloud Shell の認証情報を使用するように StackQL セッションを自動的に構成するため、すぐに Azure リソースをクエリできます。

**Google**

### Google Cloud Shell

Google Cloud Shell は、Google Cloud CLI が認証済みの状態で使える開発および運用環境を提供します。Google Cloud Shell で StackQL を実行すると、既存の認証を使用して 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
```

このスクリプトは Google Cloud Shell の認証情報を使用するように StackQL を設定するため、すぐに SQL 構文で GCP リソースのクエリを開始できます。

**Databricks**

### Databricks Web ターミナル

Databricks ワークスペースには、ログイン中のユーザーとして動作する Web ターミナルが含まれています。そこで StackQL を実行すると、個別に認証を設定することなく、Databricks の ID でワークスペースをクエリできます。クエリの例とアカウントレベルの認証については、[Databricks Web ターミナルガイド](/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
```

これにより Databricks ワークスペースの ID を使用して StackQL セッションが開始されるため、`databricks_workspace.iam.vw_user_entitlements` などのワークスペーススコープのリソースをすぐにクエリできます。アカウントレベルのクエリ（プロビジョニング、課金、アカウント IAM）を実行するには、ガイドの説明に従って Databricks OAuth2 サービスプリンシパルの変数を設定してください。

## MCP クライアントでの使用

StackQL MCP サーバーは stdio 経由でローカルに実行されるため、どのクライアントを使用してもプロバイダーの認証情報はマシン上にとどまります。以下で使用するクライアントを選択してください。各タブでは、まずディレクトリまたはワンクリックでのインストール方法を示し、代替手段として手動での構成を示します。`npx`、Python、Docker、CI を含むすべての配布チャネルについては、[MCP サーバーのインストール](#installing-the-mcp-server)を参照してください。

**Claude Desktop**

### Claude Desktop

  StackQL MCP サーバーを Claude Desktop にインストールする推奨の方法は、[Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) からのインストールです（**Settings -> Connectors -> Add -> Browse Connectors** を開き、**StackQL** を検索します）。Claude Desktop がプラットフォームに適した署名済みバイナリを自動的に選択します。また、ダウンロードしたファイルからインストールできるように、ビルド済みの MCP Bundle（`.mcpb`）がすべての StackQL リリースに添付されています。どちらの方法でも、StackQL を別途インストールする必要はありません。バンドルは macOS、Windows、Linux 向けに提供されています。

  Linux と Windows の MCPB ダウンロードのデフォルトは **amd64**（x64）です。**amd64** または **arm64** を選択するには、ドロップダウンを使用します。

  [macOS MCPB をダウンロード](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[Linux MCPB をダウンロード](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[Windows MCPB をダウンロード](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

StackQL MCP サーバーは、[__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) にも `io.github.stackql/stackql-mcp` として掲載されています。

:::

:::tip

バンドルは、StackQL MCP サーバーを実行するいくつかの方法の 1 つです。Claude Desktop の詳しい手順については [__Claude Desktop で StackQL を使用する__](/getting-started/claude-desktop)を、npx、Docker、Python、CI、手動の各オプションについては [__MCP サーバーのインストール__](#installing-the-mcp-server)を参照してください。

:::

**ChatGPT**

### ChatGPT と Codex

  StackQL は、ChatGPT デスクトップアプリと Codex CLI 向けのローカルプラグインとして提供されています。プラグインはマシン上で stdio 経由で StackQL MCP サーバーを実行するため、プロバイダーの認証情報がマシンの外に出ることはありません。Node.js 24.22.1 以降が必要です（該当するリリースラインでは 22.23.4 または 26.12.1）。プラグインに必要なのは Node.js の組み込みモジュールだけで、初回使用時に署名済みの `stackql` バイナリをダウンロードし、その SHA-256 を検証します。

  **ChatGPT デスクトップアプリ（プラグインディレクトリ）**：  

  ChatGPT デスクトップアプリでプラグインディレクトリを開き、**StackQL** を検索して **Install** をクリックしてから、プラグインのセットアップを実行します。同梱の `stackql-setup` スキルが、認証情報の設定と最初のクエリを順に案内します。掲載ページには **Desktop only** バッジが付いています。プラグインはデスクトップアプリからのみインストールでき、ChatGPT の Web 版やモバイル版からはインストールできません。また、そのツールは Work モードの、コンピューター上で実行されるスレッドで利用できます。ディレクトリにまだ掲載ページが表示されていない場合は、代わりにリポジトリマーケットプレイスからインストールしてください。

  **ChatGPT デスクトップアプリ（リポジトリマーケットプレイス）**：  

  **Settings -> Plugins -> Add -> Add from GitHub** を開き、`stackql/stackql` を入力してから、プラグインディレクトリの **Personal** セクションから **StackQL** をインストールし、アプリを再起動します。

  **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 プロバイダーをインストールしてから、最初の 5 つの GitHub サービスを一覧表示して。* プロバイダーの認証情報は、各プロバイダーの標準の環境変数名（たとえば `AWS_ACCESS_KEY_ID` と `AWS_SECRET_ACCESS_KEY`）を使用して `~/.stackql/.env` に記述します。ファイルを編集したら、`reload_credentials` を呼び出すようにエージェントに依頼します。

  **プラグインを使用しない場合**：   

  **Settings -> Plugins -> MCPs -> Connect to a custom MCP** で **STDIO** を選択し、コマンドを `npx` に設定して、引数 `-y` と `@stackql/mcp-server` を追加します。プロバイダーの認証情報は、そのフォームで環境変数として指定します。

:::note

ChatGPT の Web 版とモバイル版はローカルの stdio サーバーを実行できないため、プラグインはデスクトップアプリと Codex 専用です。ChatGPT デスクトップの未解決のバグ（[openai/codex#38162](https://github.com/openai/codex/issues/38162)）により、**Chat** セッションからローカルの MCP ツールが見えなくなることがあります。Work モードのスレッド、Codex のスレッド、Codex CLI は影響を受けません。

:::

**Goose**

### Goose

  Goose は stdio 拡張機能を直接実行するため、必要なのは `npx` ランチャーだけです（Node.js 18 以降）。

  **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 サーバーのインストール

StackQL MCP サーバーを使用すると、AI エージェントが StackQL でクラウドリソースをクエリおよびプロビジョニングできます。サーバーは複数のチャネルで配布されています。どのチャネルでも同じサーバーが動作するため、クライアントと信頼性の要件に合ったチャネルを選択してください。以下のオプションは、おおよそ信頼性と手軽さの順に並んでいます。

### マーケットプレイスとディレクトリ

サーバーは Official MCP Registry に `io.github.stackql/stackql-mcp` として公開されています。以下のパッケージレジストリが配布用のアーティファクトをホストし、下流のディレクトリはそこから掲載情報を取得します。  

**レジストリ**

| レジストリ | 種類 | 公開方法 | 掲載ページ | 備考 |
|---|---|---|---|---|
| Official MCP Registry | 正規のメタデータレジストリ | `mcp-publisher` CLI + `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 デスクトップのアプリ内ディレクトリ（デスクトップのみ） | ChatGPT デスクトップアプリで **StackQL** を検索。[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 リスト形式のサイト | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### ビルド済みの `.mcpb` バンドル

**使用場面**：Connector Directory にアクセスできない Claude Desktop の場合、または特定のバージョンに固定したい場合や、インストール前にチェックサムを自分で検証したい場合。ほとんどの 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` のいずれかです。各プラットフォームのダウンロードボタンは、[MCP クライアントでの使用](#using-with-mcp-clients)の **Claude Desktop** タブにあります。各バンドルには、対応する `.sha256` チェックサムが[リリースページ](https://github.com/stackql/stackql/releases/latest)にあります。チェックサムを検証してから、Claude Desktop の **Settings -> Extensions** からインストールします。

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

詳しい手順については、[Claude Desktop で StackQL を使用する](/getting-started/claude-desktop#install-from-a-downloaded-bundle)を参照してください。

### `claude_desktop_config.json` の手動設定

**使用場面**：`stackql` バイナリがすでに PATH 上にあり、Claude Desktop またはその他の stdio MCP クライアントを使用している場合。

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

3 つの引数はいずれも不可欠です。

- `--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` モード）を書き込みます。その構成を `claude_args` 経由で [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) に渡します。

```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` 不要、個別のインストール不要、ランタイム依存関係なし）。

ネイティブライブラリは、各言語の公式 MCP SDK クライアントの背後で、署名済みの `stackql` バイナリを stdio 経由で起動します。そのため、アプリはレジストリ内のすべてのプロバイダーに対して、同じガバナンスの効いた SQL インターフェイスを利用できます。各ライブラリのデフォルトは `read_only` で、書き込み可能なモードへの昇格は常に明示的に行います。また、初回実行時にバイナリをダウンロードして検証することも、ビルドにベンダリングして単一の自己完結型実行ファイルにすることもできます。言語ごとの API の詳細は、[組み込み MCP リファレンス](/mcp/embedded)にあります。

**Rust**

`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` ライブラリは、公式の Go MCP SDK クライアントの背後でバイナリを起動します。`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` ライブラリは、公式の Kotlin MCP SDK クライアントの背後でバイナリを起動します。また、付属の 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` パッケージは、公式の C# MCP SDK クライアントの背後でバイナリを起動します。デフォルトはサイドカー方式ですが、バンドルをビルドリソースとしてベンダリングし、自己完結型の実行ファイルにすることもできます。.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 ランタイムを対象とし、`child_spec()` を介してサーバーを OTP の子プロセスとして公開するため、独自のスーパービジョンツリーに組み込めます。デフォルトでは `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` パッケージは、公式の Swift MCP SDK クライアントの背後でバイナリを起動します。`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`

GitHub のワークフローから直接 StackQL を使用して、インフラストラクチャのスタックをデプロイまたはテストします。このアクションにより、SQL に似た構文を使用する Infrastructure as Code（IaC）ワークフローが可能になり、1 つのワークフローで複数のプロバイダーにまたがるクラウドリソースを定義、デプロイ、管理できます。  

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

GitHub Actions のワークフローで StackQL をセットアップします。  

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

GitHub Actions のワークフローに StackQL MCP サーバーをインストールします。このアクションは署名済みのバイナリをインストールし、`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`

GitHub Actions のワークフローで StackQL コマンドを実行します。クエリはインラインで指定することも、リポジトリ内のファイルから指定することもできます。  

[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**

### `pystackql` Python パッケージ

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