インストール

前提条件

必須:

Node.js >= 20.18.1
Git — プロジェクトルートとリモート URL の検出に使用します
MCP 対応のコーディングエージェント — Claude Code、Gemini CLI、OpenCode、Codex、Cursor、Windsurf など。設定方法はコーディングエージェントのセットアップを参照してください。

推奨:

Playwright — ブラウザテスト（クリック、フォーム入力、スクリーンショットアサーションなど）を含む QA プランに必要です。以下のコマンドで Chromium バイナリをインストールします。
Terminal window
```
npx playwright install chromium
```
QA プランが HTTP リクエストのみを使用する場合はスキップできます。ブラウザステップが必要なプランを実行する際、aqua がインストールを促します。

オプション — シークレットプロバイダー:

テスト環境でシークレット（API キー、パスワードなど）が必要な場合、aqua は外部のシークレットマネージャーから値を解決できます。使用するプロバイダーの CLI をインストールしてください。

プロバイダー	CLI	インストールガイド
1Password	`op`	1password.com/developers/docs/cli
AWS Secrets Manager	`aws`	docs.aws.amazon.com/cli
GCP Secret Manager	`gcloud`	cloud.google.com/sdk/docs/install
HashiCorp Vault	`vault`	developer.hashicorp.com/vault/install

外部プロバイダーなしでも、環境変数やリテラル値でシークレットを利用できます。詳細は環境設定を参照してください。

aqua アカウントを作成します。

npx @aquaqa/cli login

ブラウザが開き、認証を行います。ログインフローが完了すると、認証情報が ~/.aqua/credentials.json に保存されます。

プロジェクトリポジトリ内で以下のコマンドを実行します。

npx @aquaqa/cli init

プロジェクトルートに .aqua/config.json ファイルが作成されます。このファイルには以下の情報が含まれます。

初期化が完了すると、以降の CLI および MCP サーバーコマンドはこの設定を自動的に使用します。

開発で使用しているコーディングエージェントに aqua を接続します。エージェントごとに MCP サーバーの設定方法が異なります。

プロジェクトに aqua MCP サーバーを登録すると、すべてのセッションで利用可能になります。

claude mcp add --scope project aqua -- npx @aquaqa/cli mcp-server

プロジェクトルートに .mcp.json が作成され、バージョン管理を通じてチームで共有できます。

また、.claude/settings.json に以下を追加すると、aqua の MCP ツールが毎回の確認なしに許可されます。

{
  "permissions": {
    "allow": ["mcp__aqua__*"]
  }
}

設定ファイルを変更せずに、一回限りのセッションとして aqua MCP サーバーを起動することもできます。

claude --mcp-config '{"mcpServers":{"aqua":{"command":"npx","args":["@aquaqa/cli","mcp-server"]}}}' --allowedTools 'mcp__aqua__*'

QA 作業を開発コンテキストから分離したい場合に便利です。QA プランニングはコンテキストを大量に消費するため、QA サイクルごとに新しいセッションで始めることをおすすめします。プロジェクトメモリを活用すれば、セッション間で知見を引き継げます。

プロジェクトの Gemini CLI 設定に aqua を追加します。プロジェクトルートに .gemini/settings.json を作成または編集します。

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

プロジェクトディレクトリでセッションを開始すると、Gemini CLI が自動的に aqua MCP サーバーを起動します。

プロジェクトの OpenCode 設定に aqua を追加します。プロジェクトルートに opencode.json を作成または編集します。

{
  "mcp": {
    "aqua": {
      "type": "local",
      "command": ["npx", "@aquaqa/cli", "mcp-server"]
    }
  }
}

OpenCode が自動的に aqua MCP サーバーを検出して起動します。

codex mcp add コマンドで aqua MCP サーバーを登録します。

codex mcp add aqua -- npx @aquaqa/cli mcp-server

プロジェクトの .codex/config.toml に設定が書き込まれます。Codex はセッション開始時に自動的に aqua MCP サーバーを起動します。

Codex セッション内で /mcp と入力すると、サーバーが登録されていることを確認できます。

プロジェクトルートに .cursor/mcp.json を作成します。

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

設定を追加したら Cursor を再起動してください。Cursor Settings > MCP でサーバーの状態を確認できます。

Cascade パネル > MCP アイコン > Configure から MCP 設定ファイルを開くか、~/.codeium/windsurf/mcp_config.json を直接編集します。

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

MCP をサポートするコーディングエージェントであれば aqua を利用できます。MCP サーバーを以下のコマンドで起動します。

npx @aquaqa/cli mcp-server

サーバーは stdio で通信します。MCP サーバー接続の設定方法については、各エージェントのドキュメントを参照してください。