HCP TerraformのワークスペースをMCPから操作する

Terraform MCPサーバーは、Provider・Moduleドキュメントを検索する読み取り系ツールとは別に、HCP Terraform / Terraform Enterpriseのワークスペースを直接操作する実行系ツール群を持ちます。ワークスペースの作成・更新・削除、変数やタグの管理、Runの実行と承認までを、Claude Codeから自然文の指示で呼び出せます。

Provider・Moduleのドキュメント検索や、Sentinelポリシーの参照といった読み取り専用の使い方はTerraform MCPサーバーの使い方にまとめています。本記事はHCP Terraformの状態を実際に変更する操作に絞って扱います。

ワークスペース操作系ツールとは

ワークスペース操作系ツールとは、Terraform MCPサーバーが提供するterraformツールセットに含まれる、HCP Terraform / Terraform EnterpriseのAPIを直接呼び出すツール群のことです。組織・プロジェクトの一覧取得のような読み取り操作から、ワークスペースの作成・削除、Runの実行・承認・破棄まで、20種類以上のツールが用意されています。

読み取り系のProvider/Module検索ツールとの最大の違いは、インフラの実際の状態を変更しうる点です。公式ドキュメントも、書き込みを伴う操作を適用する前には必ず内容を検証するよう明記しています。

認証設定 — TFE_TOKENとTFE_ADDRESS

ワークスペース操作系ツールを使うには、公開Registry検索とは別にHCP Terraform / Terraform Enterpriseの認証情報が必要です。TFE_ADDRESSにAPIのエンドポイント(https://app.terraform.ioなど)、TFE_TOKENに発行したAPIトークンを渡します。

claude mcp add terraform -s user -t stdio -- docker run -i --rm \
  -e TFE_TOKEN=<your-token> \
  -e TFE_ADDRESS=https://app.terraform.io \
  hashicorp/terraform-mcp-server

トークンの権限は必要最小限に絞ることが推奨されています。組織全体を管理するトークンをそのままMCPサーバーに渡すと、AIが誤って別プロジェクトのワークスペースまで操作できてしまうためです。TLS検証をスキップするTFE_SKIP_TLS_VERIFYは既定でfalseで、テスト目的で一時的にtrueにした場合も必ずfalseへ戻すことが公式の注記にあります。

トークンが実際にどこまで操作できるかはget_token_permissionsで事前に確認できます。書き込み系のツールを呼び出す前に、そのトークンで許可されているアクションの一覧を取得しておくと、権限不足によるエラーを実行前に把握できます。

HCP Terraform上の組織・プロジェクトの構造を先に把握しておきたい場合は、list_terraform_orgsで所属組織の一覧を、list_terraform_projectsでプロジェクトの一覧を取得できます。ワークスペースを作成する前に、対象の組織IDとプロジェクトIDをこの2つで確認しておくと、create_workspaceの引数を間違えにくくなります。

書き込み系の操作を有効にするには、ENABLE_TF_OPERATIONSをtrueにしたうえでサーバーを起動します。

claude mcp add terraform -s user -t stdio -- docker run -i --rm \
  -e TFE_TOKEN=<your-token> \
  -e TFE_ADDRESS=https://app.terraform.io \
  -e ENABLE_TF_OPERATIONS=true \
  hashicorp/terraform-mcp-server

この設定は起動時にサーバー全体へ適用されるため、読み取り専用で運用したい期間はENABLE_TF_OPERATIONSを外して再起動する、という運用が現実的です。常時オンにしておくよりも、書き込みが必要な作業のときだけ有効化する方が、誤操作のリスクを抑えられます。

ワークスペースの作成・更新・削除

delete_workspace_safelyは名前のとおり、そのワークスペースが実際にリソースを管理していない場合に限って削除を実行します。管理中のリソースがあるワークスペースを誤って消してしまう事故を防ぐ設計です。

create_workspace・update_workspace・delete_workspace_safelyはいずれも、環境変数ENABLE_TF_OPERATIONSをtrueに設定していないと呼び出せません。既定はfalseで、書き込み系のツールはすべて無効化された状態から始まります。

公式ドキュメントはcreate_workspaceの返り値を「ワークスペース作成の確認(破壊的操作)」と表現しています。ここでいう「確認」は、実行結果を表すメッセージが返るという意味で、実行前に人間の承認を求める仕組みではありません。つまりENABLE_TF_OPERATIONS=trueにした時点で、AIが判断すればワークスペースの作成や削除がそのまま実行されます。

Runの実行と承認

Runとは、ワークスペースに対するplan・apply・destroyなどの一連の実行単位のことです。create_runで新しいRunを作成でき、既定ではplan_and_apply(planを作成し承認されればapply)・refresh_state(状態のみ更新)・plan_only(planのみ作成)・allow_empty_apply(変更なしでもapplyを許可)の4種類から選べます。

ENABLE_TF_OPERATIONS=trueにすると、さらにauto_approve(planを自動承認してapply)とis_destroy(destroy planの作成)が使えるようになります。Runの状況確認はlist_runs・get_run_details、apply・discard・cancelといった操作はaction_runが担当します。action_runも破壊的操作に分類され、ENABLE_TF_OPERATIONS=trueが必須です。

planとapplyの中身を確認するツールは5種類に分かれます。

CI的な使い方で「このRunで何が変わるか」をAIに要約させたいときはget_plan_json_outputが向きます。人間がそのままログを読みたい場合はget_plan_logs・get_apply_logsの生テキストのほうが扱いやすいこともあります。

変数・タグ・ポリシーセットの管理

ワークスペース単位の変数はlist_workspace_variables・create_workspace_variable・update_workspace_variableで管理します。複数のワークスペースにまたがる変数セットは別の仕組みで、list_variable_sets・create_variable_setで作成し、attach_variable_set_to_workspacesで対象のワークスペースに紐付けます。不要になったらdetach_variable_set_from_workspacesで切り離します。

同じクラウド認証情報や共通タグを毎回のワークスペースに個別入力する代わりに、変数セットとして一度作成しておけば、新しいワークスペースにアタッチするだけで済みます。ワークスペースごとに固有の値(インスタンスサイズやリージョンなど)はワークスペース変数、組織内で共通の値は変数セット、という役割分担で運用すると管理がシンプルになります。

タグはcreate_workspace_tagsで追加、read_workspace_tagsで確認します。ワークスペースにアタッチされているSentinelポリシーセットはget_workspace_policy_setsで取得でき、attach_policy_set_to_workspaceで新しいポリシーセットを紐付けられます。

プライベートモジュール・プロバイダーを検索するsearch_private_modules・search_private_providersもこのterraformツールセットに含まれます。組織内だけで公開しているモジュールを、公開Registryと同じ感覚で検索できます。

操作の流れ — ワークスペース作成からPlan確認まで

実際にステージング用のワークスペースを1つ用意する場合の流れを追うと、各ツールの役割がつかみやすくなります。

1. list_workspacesで同名のワークスペースが既に存在しないか確認する
2. ENABLE_TF_OPERATIONS=trueのもとでcreate_workspaceを呼び、新規ワークスペースを作成する
3. create_workspace_variableで必要な変数(リージョン、インスタンスサイズなど)を設定する
4. create_workspace_tagsで環境識別用のタグ(stagingなど)を付ける
5. create_runをplan_onlyで呼び、変更内容だけを確認する
6. 内容に問題がなければaction_runでapplyを実行する。自動化したい場合はauto_approve付きのcreate_runにまとめられる

このうち3と5はENABLE_TF_OPERATIONSが無くても実行できる操作です。読み取りと変数設定はデフォルトで許可され、ワークスペース自体の作成とapplyの実行だけがオプトインの対象になっている、という設計の非対称性を意識すると事故を防ぎやすくなります。

なお、Terraform MCPサーバーには「Stacks」を扱うlist_stacks・get_stack_detailsという別系統のツールもあります。Stacksは複数のコンポーネントを束ねる別の抽象概念で、単一ワークスペースの操作とは目的が異なるため、本記事では扱いません。

使い分け早見表

よくあるつまずき

create_workspaceを呼んでも「権限がない」というエラーになる。ENABLE_TF_OPERATIONS環境変数を設定し忘れているケースが大半です。この変数はサーバー起動時の環境変数であり、プロンプト側で「操作を許可して」と伝えても有効になりません。

delete_workspace_safelyが失敗する。ワークスペースが実際にリソースを管理している場合、このツールは安全のため削除を拒否します。本当に削除したい場合はHCP Terraformの管理画面から手動で確認し、リソースをdestroyしてから再度試します。

Runを作成したのにapplyまで進まない。既定のplan_and_applyは承認が必要な設計です。承認を待たずに自動でapplyまで通したいときは、ENABLE_TF_OPERATIONS=trueのうえでauto_approveオプションを明示的に指定する必要があります。

トークンの権限とツールの権限を混同する。ENABLE_TF_OPERATIONSはMCPサーバー側の設定で、HCP Terraform側のAPIトークンの権限とは別物です。トークンに書き込み権限があっても、サーバー側でオペレーションが無効なら書き込み系ツールは呼び出せません。

自社ホストのTerraform Enterpriseに繋がらない。自己署名証明書を使っている環境では、TFE_SKIP_TLS_VERIFYが既定falseのためTLS検証エラーになることがあります。一時的にtrueへ切り替えて接続確認はできますが、恒常的な運用では、証明書を正しく信頼させる設定に戻す構成が一般的です。

まとめ

HCP Terraformのワークスペース操作は、読み取り(一覧・詳細取得)はTFE_TOKENだけで動きますが、作成・更新・削除・Run実行といった書き込み操作はすべてENABLE_TF_OPERATIONS=trueという明示的なオプトインを必要とします。この2段階のガードにより、AIをHCP Terraformに接続したまま普段は読み取り専用で運用し、必要なときだけ書き込みを許可する運用がしやすくなっています。

変数やタグ、ポリシーセットの管理もこのツールセットに含まれるため、ワークスペースの新規作成から日々の運用、不要になった際の削除まで、ライフサイクル全体をClaude Code経由でカバーできます。Provider・Moduleドキュメントの検索や、Sentinelポリシーの参照方法はTerraform MCPサーバーの使い方を、MCPサーバー全般の権限設計はMCPセキュリティガイドを参照してください。