Claude Code CLI自動化の使い方｜-p・JSON出力・max-turns・Windows・MCPの安全設計
Claude Code CLIを非対話で自動化する方法を、-p/--print、JSON・stream-json出力、max-turns、Windows Native・WSL、MCP接続の確認順に整理します。
公開 2026.08.09 / 更新 2026.08.09
この記事のポイント
- -p/--print、--output-format、--max-turnsを役割ごとに分ける
- Windows NativeとWSL 2はシェル、プロジェクト位置、サンドボックス条件で選ぶ
- MCPはtransport、scope、認証、非対話実行時の承認挙動を確認してから自動化する
- CLIのJSON出力とAgent SDKを混同せず、終了コード・差分・テストを別に検証する
先に結論：Claude Code CLI自動化は4つの境界を固定する
Claude Code CLIをスクリプトやCIから呼び出すなら、最初に「どう起動するか」「何を返すか」「何ターンまで動かすか」「どの権限とMCPを渡すか」を分けます。公式CLI referenceでは、-p/--printが非対話のprint mode、--output-formatがtext・json・stream-json、--max-turnsがprint modeのagentic turn上限として案内されています。これらは自動化の部品ですが、組み合わせただけで変更の安全性や結果の正しさが保証されるわけではありません。
- 起動境界：対話セッションか、-p/--printで終了する非対話実行か
- 出力境界：人間向けtextか、機械処理向けjsonか、イベントを追うstream-jsonか
- 実行境界：--max-turnsや予算上限を置くか、許可するtoolを絞るか
- 接続境界：Windows Native／WSLと、MCPのtransport・scope・認証をどう分けるか
この記事で分かること
- Claude Code CLIの-p/--print、--output-format、--max-turns、--json-schemaの役割
- JSONを受け取る自動化側で、結果・終了コード・差分を別々に確認する理由
- Windows Native、Git for Windows、PowerShell、CMD、WSL 2の選び方
- MCPのstdio・HTTP・scope・認証・非対話実行時の注意点
- MCPのHTTP／SSE／WebSocketの違い、workspace trust、CLIログインを確認する方法
- Agent SDKを使う場合と、CLIをsubprocessとして呼ぶ場合の分け方
CLIの主要フラグを役割で分ける
| フラグ | 公式Docs上の役割 | 自動化での見方 | 混同しやすい点 |
|---|---|---|---|
| -p / --print | 非対話のprint modeで応答を出して終了 | スクリプトや別言語から呼ぶ入口 | 対話しないことと安全な権限は別 |
| --output-format | text・json・stream-jsonを選ぶ | 後段が読む形式を固定する | JSONでも成功判定やschema検証まで自動ではない |
| --max-turns | print modeのagentic turn数を制限 | 終わらない実行の上限を置く | 時間制限、費用上限、権限の代わりではない |
| --json-schema | 完了後のJSON出力をschemaに合わせる | 後段で読む構造を明示する | 自由文のJSON化と同じではない |
| --permission-mode | セッション開始時の権限モードを選ぶ | 自動処理の初期条件を明示する | モード名だけで差分・本番影響の確認は不要にならない |
| --mcp-config | MCP server設定を読み込む | 接続先を実行ごとに限定する | MCPの権限や認証を自動で安全にしてくれない |
| --strict-mcp-config | --mcp-configで指定したMCPだけを使う | 実行ごとの接続範囲を狭める | 指定ファイルが正しいことやtoolの安全性を保証しない |
まずは小さなprint modeから始める
最初の自動化は、ファイルを書き換えない調査やレビューから始めます。次の例は、非対話でJSONを返し、agentic turnを2回までに制限する最小形です。実際に書き込みを許可するかどうかは、リポジトリ側の設定と権限モードを別途確認してください。
claude -p --output-format json --max-turns 2 --permission-mode plan "変更せずに、srcの構成と確認すべきテストを要約してください"- プロンプトで「変更しない」「対象ディレクトリ」「出力してほしい観点」を明示する
- --output-format jsonは後段のパーサーが読む形式であり、成功したという意味ではない
- --max-turnsはループの上限で、長い処理の時間・料金・権限を一括管理するものではない
- CIに組み込む前に、同じ引数をローカルの一時コピーで実行し、stdout・stderr・終了コードを確認する
JSON出力を受ける側で確認すること
JSONを受け取る自動化では、AIの文章をそのまま成功扱いしないことが大切です。少なくとも、プロセスの終了コード、JSONとして解釈できたか、期待する項目があるか、ファイル差分が想定範囲か、テストやbuildが通ったかを分けて確認します。出力形式を固定しても、生成された変更が正しいとは限りません。
| 確認層 | 見るもの | 失敗時の扱い |
|---|---|---|
| プロセス | 終了コード、タイムアウト、stderr | 自動成功にせずログを保存して停止 |
| 出力 | JSON parse、schema、必須項目 | 後段処理を進めず、形式エラーとして扱う |
| 変更 | git diff、対象ファイル、秘密情報の混入 | 差分を人間確認し、必要なら戻せる状態で止める |
| 品質 | lint、test、build、主要URL | AIの回答ではなく成果物の確認結果を採用する |
後段システムが厳密な構造を必要とするなら、自由文に「JSONで答えて」と書くだけではなく、公式CLI referenceにある--json-schemaの利用を検討します。それでもschema検証は内容の妥当性を保証しないため、変更差分やテストの確認は残します。イベント単位で進捗を監視したい場合はstream-jsonを検討しますが、通常のJSONとパーサーを混ぜないようにします。
Windows NativeとWSL 2は、プロジェクトの場所で選ぶ
Anthropicの現行セットアップDocsでは、Claude CodeはWindows NativeとWSLで利用できます。Native WindowsはWindowsのプロジェクトやツールを扱う入口で、Git for WindowsはBash toolを使いたい場合の選択肢です。WSL 2はLinux toolchainやsandboxed command executionを使いたい場合に向きます。Native WindowsとWSL 2では、同じリポジトリでもPATH、ホームディレクトリ、設定ファイル、実行されるshellが変わるため、片方で動いたMCPやスクリプトをもう片方の前提で扱わないようにします。
| 環境 | 公式Docsの位置づけ | 先に固定する項目 |
|---|---|---|
| Native Windows | Windows-native projects and tools。サンドボックスは非対応 | PowerShell／CMD、PATH、Git Bashの有無、Windows側の設定場所 |
| WSL 2 | Linux toolchainやsandboxed command execution向け | WSL内のPATH、Linux側のrepo位置、Linux側の設定・認証 |
| WSL 1 | WSL 2が使えない場合の選択肢。サンドボックスは非対応 | 実行制約とWindows側とのファイル境界 |
- 最初にclaude --versionを確認し、PowerShell、CMD、Git Bash、WSLのどこから起動したかを記録する
- Windows側とWSL側で同じ設定ファイルを共有していると決めつけない
- Native WindowsでGit for Windowsを使う場合は、Claude CodeがGit Bashを見つけられるかを確認する
- 自動化のログに、repoの絶対パス、shell、Claude Codeのバージョン、使用したMCP config名を残す
MCPはtransport・scope・認証を先に分ける
Claude CodeのMCP Docsでは、remote HTTP、SSE、local stdio、WebSocketを別のtransportとして扱い、claude mcp listやclaude mcp getで接続状態を確認できます。現行DocsではHTTPがremote接続の推奨で、SSEはdeprecated、WebSocketは別の設定・認証条件です。JSON設定では`streamable-http`をHTTPのtype aliasとして使えますが、urlだけでtypeを省くとstdioとして扱われてserverが読み込まれないため、transportを明示します。自動化では「接続できるか」だけでなく、どのプロセスを起動し、どの環境変数やheaderを渡し、どのscopeに保存したかを記録します。
claude mcp list
claude mcp get YOUR_SERVER_NAME
claude mcp login YOUR_SERVER_NAME
claude mcp logout YOUR_SERVER_NAME
claude mcp add --transport stdio YOUR_SERVER_NAME -- npx -y YOUR_MCP_SERVER_PACKAGE- stdioはローカルプロセスを起動するため、command、args、PATH、Node／Pythonの実体を確認する
- HTTPは推奨transportとしてURL、header、OAuthを確認し、SSEはdeprecatedで代替可能かを確認する。tokenをリポジトリへ直書きしない
- WebSocketはHTTPと異なり、--transport flagやOAuthの扱いが同じではないため、公式の設定項目を分けて読む
- project scopeはチーム共有に便利だが、.mcp.jsonをレビューしてからcommitする
- user scopeは個人の全プロジェクトから見えるため、共有repoに持ち込まないものを分ける
- --mcp-configで実行ごとに読む設定を限定しても、接続先の権限設計までは代替しない
MCPのscopeとWindows managed configを混同しない
現行のClaude Code MCP Docsでは、local、project、user、plugin、claude.ai connectorの設定を別のscopeとして扱い、同じserver名の優先順位も案内されています。localは現在のprojectだけ、projectは.mcp.jsonでteam共有、userは全projectから見える設定です。pluginやconnectorまで含めた優先順位を確認せず、同名serverを複数箇所へ置くと、想定と違うcommandやendpointが起動する可能性があります。
| scope | 主な用途 | 先に確認すること |
|---|---|---|
| local | 個人の現在projectだけで使うserver | 他projectへ広がらないこと、個人credential、実際の保存先 |
| project | チームで共有する.mcp.jsonのserver | version管理、project approval、serverの出所とtool allowlist |
| user | 自分の全projectで使うutilityやremote server | 意図しないrepoにも見えること、scopeとcredential |
| plugin / connector | bundleやclaude.aiから提供されるserver | 手動設定との重複、認証方法、管理者ポリシー |
組織管理では、managed-mcp.jsonによるexclusive controlと、allowedMcpServers／deniedMcpServersによるpolicy controlを分けます。現行DocsではWindowsのsystem-wide managed configの例として`C:\Program Files\ClaudeCode\managed-mcp.json`が案内されています。これは管理者が配布する設定であり、個人projectの.mcp.jsonへコピーして使う設定ではありません。
stdioのproject pathとCLAUDE_PROJECT_DIRを固定する
Claude Codeがstdio MCP serverをspawnするとき、serverの環境にはCLAUDE_PROJECT_DIRが渡され、MCP serverはproject rootを解決するために利用できます。起動時のworking directoryだけを信頼すると、Native Windows、Git Bash、WSL、別のshellで相対pathが変わることがあります。server側でCLAUDE_PROJECT_DIR、roots/list、command、args、cwdのどれを使うかを決め、ログには実行環境と解決後の対象pathを残します。
| 確認点 | 意味 | 安全側の運用 |
|---|---|---|
| CLAUDE_PROJECT_DIR | spawnされたMCP serverが参照できるproject root | 許可repoの範囲と一致するかをserver側で確認する |
| roots/list | client側から返るroot情報 | pathを未検証のまま外部送信や全体探索へ使わない |
| working directory | process起動時の相対pathの基準 | Native／WSL／shellごとに実値を記録する |
| env expansion | .mcp.jsonのcommand・args・envなどで展開される変数 | 未設定時のdefaultとsecretの露出を確認する |
MCPの再接続と出力上限を自動化の条件に入れる
現行MCP Docsでは、HTTPやSSE serverが切断した場合に指数backoffで再接続し、stdio serverは自動再接続しないと説明されています。HTTP／SSEは初期接続の一時エラーも一定回数retryされますが、認証やnot-foundは設定変更が必要なため同じようにretryされません。自動化では「retryするから放置できる」と考えず、server種別、retry回数、timeout、認証失敗、最終停止をログで区別します。
| 観点 | HTTP／SSE | stdio |
|---|---|---|
| 切断時 | 指数backoffで再接続を試す | local processのため自動再接続しない |
| 認証失敗 | retryで直らない場合があり、設定変更が必要 | process起動やenv、credential経路を確認する |
| 自動化の境界 | retry上限、timeout、再認証、重複tool call | process終了、stderr、再起動手順、side effect |
MCP toolの出力が10,000 tokensを超えるとClaude Codeは警告を表示し、既定の上限は25,000 tokensです。MAX_MCP_OUTPUT_TOKENSで上限を上げられますが、出力上限を増やすだけでなく、tool側のfilter、ページング、read-only query、ログ保存先を設計し、contextを埋める大量結果をそのまま後段へ渡さないようにします。
WindowsでMCPが動かないときの切り分け順
| 症状 | 最初に見る場所 | 避けたい判断 |
|---|---|---|
| serverが見つからない | claude mcp list、claude mcp get、実行shellのPATH | 別のshellで動いたから同じ環境だと決めつける |
| stdioがFailedになる | command／args、--の位置、Node／Pythonの実体、stderr | API keyや権限を先に増やす |
| interactiveでは動くが-pで失敗する | project scope、承認、非対話時の起動条件、--mcp-config | 人間の承認UIが自動実行でも出ると期待する |
| JSONをparseできない | stdoutとstderr、text／json／stream-jsonの指定 | 自由文をJSONとみなして後続処理を続ける |
| Windowsだけ再現する | PowerShell／CMD／Git Bash／WSL、PATH、引用符、改行 | cmd /cなどの回避策を根拠なく追加する |
最後の行は特に重要です。WindowsのMCP障害では、shell差、実行ファイルのPATH、引数の引用、設定ファイルの場所が同時に変わり得ます。原因が分からないままラッパーや権限を足すと、再現条件がさらに見えなくなります。まずclaude mcp list／get、設定のtransport、command／url、実行環境を一つずつ固定します。これは公式Docsのコマンドと設定項目を使った切り分けであり、すべてのserverに通用する修正を断定するものではありません。
CLIとAgent SDKをどう分けるか
AnthropicのAgent SDK overviewでは、SDKはPythonとTypeScriptで利用でき、別の言語から同じagent loopを動かす場合はCLIを-pと--output-format jsonでsubprocessとして呼ぶ方法が案内されています。つまり、CLIのJSON出力はSDKそのものではありません。小さなバッチや既存のPowerShell／Node／Python処理ならCLI呼び出し、細かなイベント制御や長期運用のアプリケーションならSDKを比較します。
| 選択肢 | 向いている場面 | 先に設計すること |
|---|---|---|
| CLI -p | 既存scriptから一回の調査・レビュー・小さな処理を呼ぶ | 引数、stdout／stderr、終了コード、turn上限 |
| CLI stream-json | 進捗やイベントを監視しながら処理する | イベント種類、再接続、ログ量、パーサー |
| Agent SDK | Python／TypeScriptアプリにagent loopを組み込む | session、tool、permission、MCP、エラー処理 |
公開前に使える安全チェックリスト
- claude --version、起動shell、repo path、設定ファイルの場所を記録した
- -p、output format、max-turns、permission mode、MCP configをコマンドに明示した
- stdout／stderr／終了コードを分け、JSON parseやschema検証の失敗で止まるようにした
- AIに変更を許可する場合も、git diff、秘密情報、対象ファイル、test／buildを人間が確認する
- MCPのtransport、scope、認証、server health、project approvalを確認した
- Windows NativeとWSLのどちらで実行したかをログに残し、別環境の成功をそのまま流用しない
- CLIの現行Docsと自分のインストール済み版が一致しているか再確認した
Claude Code CLI自動化のFAQ
Claude Codeの-p/--printは何に使いますか？
対話UIを開かずにpromptを実行し、応答を出して終了するprint modeの入口です。自動化に向きますが、非対話であることは安全な権限や正しい変更を保証しません。
--output-format jsonなら自動化は安全ですか？
いいえ。JSONは後段で扱いやすい出力形式です。終了コード、JSON parseやschema、git diff、test、buildを別々に確認してから成功と判断します。
--max-turnsは何を制限しますか？
print modeでのagentic turn数を制限します。時間、料金、tool権限、生成変更の正しさを一つで管理するフラグではありません。
WindowsではNativeとWSLのどちらを選ぶべきですか？
Windowsのプロジェクトやツールを中心に使うならNative、Linux toolchainやsandboxed command executionが必要ならWSL 2を候補にします。実際のrepo位置、shell、PATH、MCP設定を合わせて選びます。
MCPを-pで使うとき、人間の承認画面は出ますか？
公式Docsでは、project-scoped serverについてclaude -pやAgent SDKは対話的な承認promptを表示できないと説明されています。自動化前に設定、scope、tool、認証を人間が確認してください。
projectのMCPがPending approvalのままなのはなぜですか？
未信頼のworkspaceでは、cloneしたrepoのproject settingsが自分のMCP serverを承認する設定であっても、承認経路として扱われない場合があります。folderのtrust、claude mcp list／getの状態、user・managed・--settingsのどの経路を使うかを分けて確認してください。
CLIとAgent SDKは同じものですか？
同じではありません。Agent SDKはPythonとTypeScriptのlibraryで、別言語から同じagent loopを使う場合はCLIをsubprocessとして呼ぶ方法が公式に案内されています。
まとめ：自動化の前に、終了条件と権限境界を固定する
Claude Code CLIを自動化するなら、-pで起動し、output formatを固定し、max-turnsや必要な権限を絞り、Windowsの実行環境とMCPの接続条件を記録します。JSONが返ったことやMCPがconnectedになったことだけで、変更が安全・正確だとは判断しません。最後はgit diff、秘密情報、test、build、公開範囲を人間が確認する。この境界を先に決めておくと、CLIの便利さを使いながら、止めるべき処理を止めやすくなります。