メインコンテンツまでスキップ
翻訳ページ

このページは AI の支援を受けて英語から翻訳されています。内容が異なる場合は英語版が正となります。

インストール

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

macOS​

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

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

brew install stackql

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

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

Claude Desktop​

StackQL MCP サーバーを Claude Desktop にインストールする推奨の方法は、Anthropic Connector Directory からのインストールです（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 をダウンロード  
Linux MCPB をダウンロード  
Windows MCPB をダウンロード  

備考

StackQL MCP サーバーは、Official MCP Registry にも io.github.stackql/stackql-mcp として掲載されています。

ヒント

バンドルは、StackQL MCP サーバーを実行するいくつかの方法の 1 つです。Claude Desktop の詳しい手順については Claude Desktop で StackQL を使用するを、npx、Docker、Python、CI、手動の各オプションについては MCP サーバーのインストールを参照してください。

MCP サーバーのインストール​

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

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

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

レジストリ種類公開方法掲載ページ備考
Official MCP Registry正規のメタデータレジストリmcp-publisher CLI + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct		8 つのパッケージすべてを公開（mcpb x5、oci、npm、pypi）
npmパッケージレジストリnpm publish@stackql/mcp-servernpx ランチャー
PyPIパッケージレジストリtwine uploadstackql-mcp-serveruvx / pip ランチャー
Docker Hubコンテナーレジストリdocker buildx --pushstackql/stackql-mcpマルチアーキテクチャ amd64 + arm64
GitHub Actions MarketplaceCI マーケットプレイス（setup-stackql-mcp アクション）パブリックリポジトリ + リリース + マーケットプレイスの掲載ページsetup-stackql-mcp-server検証済みパブリッシャー、stackql/setup-stackql-mcp

ビルド済みの .mcpb バンドル​

使用場面：Connector Directory にアクセスできない Claude Desktop の場合、または特定のバージョンに固定したい場合や、インストール前にチェックサムを自分で検証したい場合。ほとんどの Claude Desktop ユーザーには、Anthropic Connector Directory が推奨のインストール方法です。

すべての 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 クライアントでの使用の Claude Desktop タブにあります。各バンドルには、対応する .sha256 チェックサムがリリースページにあります。チェックサムを検証してから、Claude Desktop の Settings -> Extensions からインストールします。

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

詳しい手順については、Claude Desktop で StackQL を使用するを参照してください。

claude_desktop_config.json の手動設定​

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

{
  "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" で調整します。サーバーモードを参照してください。

npx（インストール不要）​

使用場面：任意の Node 環境で、StackQL をグローバルにインストールしたくない場合。

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

@stackql/mcp-server ランチャーは、初回実行時に署名済みの stackql バイナリをダウンロードし、その SHA-256 を検証して、以降の実行のためにキャッシュします。

uvx / pip（Python）​

使用場面：Python 環境の場合。Python 向けにパッケージ化された同じランチャーで、npx ランチャーが作成するバイナリキャッシュを共有します。

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

または、pip install stackql-mcp-server（Python 3.9 以降）で現在の環境にインストールします。パッケージは PyPI の stackql-mcp-server です。

Docker​

使用場面：コンテナー化された、またはその他の方法で分離されたランタイムの場合。イメージはマルチアーキテクチャ（amd64 と arm64）です。

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

クライアント構成として指定する場合は次のとおりです。

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

イメージは Docker Hub の stackql/stackql-mcp です。

CI とエージェント型ワークフロー（GitHub Actions）​

使用場面：GitHub Actions のジョブ内でサーバーを実行し、CI の一環としてエージェントがクラウドをクエリできるようにする場合（許可した場合はクラウドに対する操作も可能）。

stackql/setup-stackql-mcp@v1 はバイナリをインストールし、MCP 構成（デフォルトは read_only モード）を書き込みます。その構成を claude_args 経由で anthropics/claude-code-action に渡します。

- 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 を参照してください。

組み込み MCP​

使用場面：エージェント型アプリを構築していて、MCP サーバーを独自のバイナリにベンダリングしたい場合（npx 不要、個別のインストール不要、ランタイム依存関係なし）。

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

stackql-mcp クレートは、rmcp クライアントの背後でバイナリを起動します。デフォルトの sidecar 機能は、初回実行時にバイナリをダウンロードして検証します。vendored 機能は include_bytes! でバイナリを組み込み、単一の自己完結型バイナリにします。MSRV は Rust 1.88 です。

# Cargo.toml
stackql-mcp = "0.1"
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
    .mode(Mode::ReadOnly)
    .start()
    .await?;
let tools = server.list_all_tools().await?;
GitHub で表示  
crates.io で表示  

詳細なリファレンス：組み込み MCP：Rust。

信頼モデル​

どのチャネルでも同じセキュリティ特性が成り立ちます。

  • 組み込まれた stackql バイナリは Authenticode 署名済み（Windows）、Apple 公証済み（macOS）です。
  • すべての .mcpb バンドルには、リリースページで公開されている SHA-256 チェックサムがあります。
  • npx と uvx のランチャーは、初回使用前にダウンロードしたバイナリの SHA-256 を検証します。
  • MCP Registry のエントリは、プラットフォームごとのハッシュを証明します。

GitHub Actions の使用​

StackQL GitHub Actions は、GitHub Actions のワークフローで使用できます。次のアクションを利用できます。

stackql-deploy​

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

GitHub Marketplace で表示  
GitHub で表示  

使用例

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

その他のライブラリ​

StackQL には、さまざまなプログラミング言語や環境で使用できる複数の統合方法が用意されています。これらのライブラリは StackQL の機能を拡張し、クラウドリソースのクエリと管理を既存のアプリケーションやワークフローに簡単に組み込めるようにします。

pystackql Python パッケージ​

Python プログラムで StackQL を使用するための Python ラッパーです。pystackql パッケージは PyPI で入手でき、pystackql パッケージのドキュメントは Read the Docs で参照できます。pystackql パッケージをインストールするには、次のコマンドを実行します。

pip install pystackql

次の例では、pystackql パッケージを pandas と組み合わせて使用し、StackQL クエリを実行して結果を pandas.DataFrame に返します。

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)