Terraform MCP Serverとは？導入手順とtoolsetの権限設計を実装目線で解説

AIコーディング支援にTerraformのコードを書かせると、学習時点の古いprovider構文が返ってくることがあります。Terraform MCP Serverは、その穴をTerraform Registryへの実時間の問い合わせで埋めるHashiCorp公式のMCPサーバーです。この記事では、v1.2.0（2026-08-04公開）のソースと公式リファレンスをもとに、3つのtoolsetが公開する60本のtoolの内訳、stdioとstreamable-httpの選び分け、Docker起動とTFE_TOKENの渡し方、クライアント別の設定形式の差、ENABLE_TF_OPERATIONSが既定で閉じている破壊的操作の範囲、そして集中デプロイ時の組織allowlistの仕様まで整理します。版を固定した社内リポジトリでregistry参照が裏目に出る条件も条件付きで言い切ります。

まとめ：入れる判断とtoolsetをどこまで開けるかの結論

結論から言えば、最初はregistry toolsetだけ、stdioで個人ローカルに配る形が失敗しません。この構成ならTFE_TOKENすら不要で、公開レジストリのprovider・module・Sentinelポリシーの検索と詳細取得だけが開きます。読み取りしか起きないため、社内の承認プロセスを通す必要もほぼ生じません。

HCP TerraformやTerraform Enterpriseのワークスペースまで触らせたくなった段階で、判断が2つ増えます。ひとつはterraform toolsetを開けるかどうか、もうひとつは個人ごとにトークンを分けるために集中デプロイへ移すかどうかです。terraform toolsetは47本のtoolを含み、その中に破壊的な操作が混ざっています。これらはENABLE_TF_OPERATIONSが既定でfalseのため閉じていますが、フラグを立てるときはトークンのスコープと合わせて設計しないと、AIの判断ひとつでrunが走る状態になります。

逆に、providerの版をlockで固定し、破壊的変更を追わない方針のリポジトリでは、registry参照が提案の質を下げる側に回ります。最新版のリソース引数を提案され、lockで固定した版では通らないコードが混ざるためです。この場合はtoolsetを絞るか、そもそも入れない判断のほうが運用は軽くなります。

Terraform MCP Serverがregistry参照で埋める学習データの穴

MCPサーバーとしての位置づけと、公開されるtoolの実際の粒度を先に押さえます。

MCPサーバーがRegistry APIを叩く仕組みと版ずれの発生源

Model Context Protocolは、AIモデルと外部データソースをつなぐ規格です。規格そのものの仕組みはMCPの標準規格とMCPサーバーの役割で整理しています。Terraform MCP Serverはその実装のひとつで、モデルからの要求を受けてTerraform RegistryのAPIへ問い合わせ、結果を返します。

版ずれが起きる理由は単純です。hashicorp/aws は2026-08-13に6.60.0が出ており、google は7.44.0（2026-08-11公開）、azurerm は5.0.1（2026-07-30公開）と、メジャー番号すら揃っていません。学習データの締め切りが半年前のモデルは、その時点の引数名とブロック構造で書きます。get_latest_provider_version と get_provider_details を通せば、モデルは記憶ではなく現在のレジストリの記述を根拠にできます。

registry系2種とterraform toolsetが持つtoolの内訳

v1.2.0の pkg/toolsets/mapping.go を数えると、公開されるtoolは合計60本でした。内訳は下表のとおりです。

registryは公開レジストリのprovider・module・Sentinelポリシーを扱う9本で、search_providers、get_provider_details、get_latest_provider_version、get_provider_capabilities、search_modules、get_module_details、get_latest_module_version、search_policies、get_policy_details が含まれます。terraformの47本には組織・プロジェクト・チーム・ワークスペース・run・変数・タグ・Stacks・stateバージョンの操作が入ります。絞り込みは --toolsets（グループ単位）か --tools（個別指定）で行い、READMEでは両者を併用できない仕様です。

HashiCorp公式版とAWS Labs版の機能差と選び分けの条件

同名で紛らわしいのですが、AWS Labs が公開する terraform-mcp-server は別実装です。あちらは ExecuteTerraformCommand や ExecuteTerragruntCommand でCLIそのものを走らせ、RunCheckovScan でセキュリティスキャンまで回します。AWS-IAのGenAI系モジュールを優先的に探し、AWSCC providerを先に検討する方針も持っています。

HashiCorp公式版にはCLI実行toolもCheckov連携もありません。代わりにHCP Terraform／Terraform EnterpriseのAPI操作を47本のtoolで持ちます。選び分けの条件は明快です。ローカルで terraform plan をAIに走らせたいならAWS Labs版、HCP Terraformのワークスペースとrunを主戦場にするなら公式版になります。AWS専業でCheckovをすでに回しているならAWS Labs版、マルチクラウドでレジストリ参照の精度を上げたいだけなら公式版のregistry toolsetで足ります。

stdioとstreamable-httpの選択条件とクライアント別の接続設定

接続形態は2つあり、選び方で運用の重さがまるで変わります。

stdioとstreamable-httpを分ける2つの判断材料

既定は stdio です。TRANSPORT_MODE を streamable-http に変えるとHTTPになり、エンドポイントは /mcp、ヘルスチェックは /health、待ち受けは 127.0.0.1 の8080番になります。判断材料は2つだけです。ひとつ、利用者が自分のマシンだけで完結するか。ふたつ、誰がどのtoolを呼んだかを記録に残す必要があるか。

両方とも「そうではない」ならstdioで終わります。公式ドキュメントも、Terraform環境を外部へ晒さないためローカルの127.0.0.1で動かすことを勧めています。逆に、複数人に配ってトークンを個別管理したいなら、HTTP側でないと成立しません。

Dockerでのstdio起動とTFE_TOKENを渡す位置の書き分け

公式イメージは hashicorp/terraform-mcp-server で、タグにバージョンを指定できます。起動から接続までの順序は次のとおりです。

1. Docker Engine v20.10.21以降、またはDocker Desktop v4.14.0以降を用意する
2. 公開レジストリだけで足りるなら、環境変数なしで docker run -i --rm により stdio で起動する
3. HCP Terraform を触るなら TFE_ADDRESS にプロトコル込みのアドレスを、TFE_TOKEN にAPIトークンを渡す
4. クライアント側の設定ファイルに、上記のコマンドと引数をそのまま登録する

TFE_ADDRESS はプロトコルを含める必要があり、既定は app.terraform.io です。Terraform Enterpriseを自ホストしていて社内認証局の証明書を使う場合は TFE_SKIP_TLS_VERIFY がありますが、これは検証を止める設定なので常用しないでください。トークンを渡さない構成では registry の9本しか動かず、private registry と terraform の51本は呼び出せません。

VS Code・Cursor・Claude Code・Codex CLIの設定形式の差

同じサーバーでも、クライアントごとに書き場所とキーの階層が違います。VS Code はユーザー設定JSONの mcp 直下に servers を置き、inputs でトークンを promptString として都度入力させられます。password を true にすれば入力値が伏せ字になり、設定ファイルへの平文書き込みを避けられる仕組みです。

Cursor は ~/.cursor/mcp.json に mcpServers を書く形式です。Claude Desktop・Amazon Q Developer・Kiro CLI も mcpServers の形式で共通です。Claude Code と Codex CLI はCLIから追加でき、stdioなら claude mcp add terraform -s user -t stdio -- の後ろにdockerコマンドを続け、HTTPなら --transport http にエンドポイントURLを渡します。Gemini拡張やBob IDEの設定例もREADMEに載っています。差が出るのはキーの階層とトークンの入力方法だけなので、1クライアントで動いたら他への移植は機械的な作業です。

ENABLE_TF_OPERATIONSが遮断する破壊的toolと承認の設計

terraform toolsetを開けるかどうかは、フラグ1つの話ではなく運用ルールの話になります。

既定でfalseのフラグが閉じるtoolと読み取り専用で足りる範囲

ENABLE_TF_OPERATIONS の既定値は false です。READMEはこれを「明示的な承認を要するtoolを有効化する」設定と説明しています。公式リファレンスは破壊的操作として create_workspace、update_workspace、delete_workspace_safely、action_run を挙げ、create_run も一部のrun種別でフラグを要求します。

調査目的なら、フラグを立てずに済む範囲がかなり広いことに気づきます。list_workspaces でワークスペースを列挙し、list_runs と get_run_details でrunの履歴を追い、get_plan_json_output と get_plan_logs で差分の中身を読み、list_state_versions と get_state_version でstateの世代をたどる。この流れは全て読み取り側です。「なぜこのapplyが失敗したのか」をAIに調べさせる用途は、既定値のままで成立します。

create_runとaction_runを開ける前に決める承認ルール

フラグを立てるなら、先に決めておくことが3つあります。誰のトークンで動くのか。planまでで止めるのか、applyまで進ませるのか。実行の記録をどこに残すのか。この3つが決まっていない状態でtrueにするのは、レビューを飛ばしてapplyを許すのと同じです。

実務では、変更の適用経路はPull Request側に残しておくのが安全です。PRにplan結果を貼ってレビューを通す運用はAtlantisでTerraformをPR運用する構成と権限設計で整理しています。MCP経由の create_run は、あくまで調査や再実行の補助に限定し、承認フローの代替にはしない。この線引きを崩すと、事故の原因追跡ができなくなります。

whoamiとget_token_permissionsで実効権限を先に測る手順

terraform toolsetには whoami と get_token_permissions が用意されています。前者は現在のトークンが誰として認識されているか、後者はそのトークンで何ができるかを返します。フラグを立てる前に、この2本で実効範囲を確かめてください。

HCP Terraformのトークンはユーザー・チーム・組織の3種類があり、それぞれ到達できる範囲が違います。個人のユーザートークンをそのまま渡すと、その人が持つ全組織・全ワークスペースがMCP経由で見える状態です。チームトークンに切り替えて対象を絞るだけで、露出はかなり減ります。ワークスペース単位の権限設計はHCP Terraform（旧Terraform Cloud）の機能と料金の側で決まるため、そちらの設定を先に確認するのが正しい順序です。

集中デプロイでのトークン受け渡しと組織allowlistの制限

複数人で1つのサーバーを共有する構成には、専用の制約がいくつも入っています。

MCP_ORGANIZATION_ALLOWLISTがBearerに課す所属条件

集中デプロイでは、サーバー側にトークンを置かず、利用者ごとのトークンをHTTPヘッダで渡す形が取れます。この設計にRBACを効かせるのが MCP_ORGANIZATION_ALLOWLIST です。HCP Terraformの組織名をCSVで並べると、サーバーは Authorization: Bearer を必須にし、そのトークンがCSV内のいずれか1つの組織にアクセスできない限りリクエストを拒否します。

細かい挙動を3点だけ押さえてください。組織名の照合は大文字小文字を区別しません。TFE_TOKEN ヘッダとBearerが同時に来た場合はBearer優先です。そしてCSVを設定したのに組織名が1つも解釈できなかった場合、サーバーは起動時にallowlistの書式エラーで終了します。設定ミスを黙って素通りさせない作りになっています。

TFE_ADDRESSをクライアントが設定できない仕様と403の意味

streamable-httpモードでは、接続先のTerraformアドレスはサーバー側の TFE_ADDRESS だけで決まります。クライアントがHTTPヘッダやクエリパラメータで指定しようとすると403で拒否されます。これは、悪意あるクライアントが接続先を差し替えてAuthorizationヘッダごと外部へ送らせる経路を塞ぐためです。

トークンをクエリパラメータに載せた場合は400を返します。ログやプロキシに残る形でトークンが漏れる経路を、仕様として閉じている格好です。localhost以外へ配備するなら MCP_TLS_CERT_FILE と MCP_TLS_KEY_FILE が要り、CORSは MCP_CORS_MODE が既定でstrict、接続元は MCP_ALLOWED_ORIGINS で明示します。403や400が出たときは、まずこの4つのどれに当たったかを切り分けてください。

MCP_SESSION_MODEのstatelessとレート制限の既定値

セッションの持ち方は MCP_SESSION_MODE で切り替えます。既定は stateful で、リクエスト間の状態を保持する方式です。ロードバランサの背後に複数レプリカを置く構成では、リクエストがどのレプリカに着いても成立するよう stateless へ変更します。

レート制限は既定で全体が10:20、セッション単位が5:10（いずれもrps:burst）です。エージェントは1つの指示から連続でtoolを呼ぶため、人数が増えると全体側の上限に先に当たります。OTEL_METRICS_ENABLED をtrueにすると mcp_tool_calls_total、mcp_tool_errors_total、mcp_tool_duration_seconds が出るので、上限の調整はこの実測を見てから行ってください。複数のMCPサーバーをまとめて配る設計そのものはDocker MCP GatewayでMCPサーバーを集約する使い方と共通の論点になります。

Terraform MCP Serverを入れない方がよい構成と代替の条件

ここからは判断を言い切ります。全てのTerraform運用にこのサーバーが要るわけではありません。

版を固定した社内リポジトリでregistry参照が裏目に出る条件

registry toolsetは最新情報を返す仕組みです。get_latest_provider_version はその名のとおり最新版を返し、get_provider_details もレジストリ上の現行ドキュメントを返します。ところが社内リポジトリでは .terraform.lock.hcl による版の固定が一般的です。ここが噛み合わないと、モデルは最新版の引数で書き、applyやvalidateで初めて弾かれます。

見送りの条件をはっきりさせます。providerの版を1年以上動かしておらず、破壊的変更を追う予定も無いリポジトリでは、registry toolsetを入れる価値はほとんどありません。この場合はレジストリ参照よりも、required_providers の制約と現行版のドキュメントをリポジトリ内に置いてモデルへ渡すほうが精度が出ます。制約の桁の決め方とlockの運用はterraform providerのバージョン制約とalias設計で扱っています。入れるなら、版を追い続ける方針とセットにしてください。

MCPサーバーを個人ローカルに配るか集中運用に寄せるかの判断基準

この判断は2問で決まります。第1問、TFE_TOKENを人ごとに分け、誰がどのワークスペースを見られるかを分離する必要があるか。第2問、tool呼び出しの記録を残し、監査や障害調査に使う必要があるか。

両方ともYesなら、streamable-httpの集中デプロイにトークンpassthroughと組織allowlistを組み合わせ、OTelメトリクスを取ります。どちらか一方でもNoなら、stdioで各自のマシンに配って終わりです。TLS証明書の管理もレート制限の調整も要らなくなります。中間の「とりあえずHTTPで社内に1台立てる」がいちばん割に合いません。認証設計を省いたまま社内へ公開すると、トークンを持つ全員が同じ権限で動く状態になるためです。エージェントを業務プロセスへ組み込む段階まで進めるなら、権限分離と記録の設計を含めてAIエージェント開発の側で引き受けています。

terraform planのレビューを人が持ち続ける理由と事故の型

READMEのSecurity Noteは、信頼できないMCPクライアントやLLMと組み合わせて使わないよう明記しています。実際に想定される事故は3つの型に整理できます。

• ENABLE_TF_OPERATIONSをtrueにしたうえで広い権限のトークンを渡し、AIの判断でrunが走る
• registry参照で最新版の記法を提案され、lockで固定した版と食い違ったコードが混ざる
• registry-privateを開けたことで、社内モジュールの内容がそのままLLM側へ渡る

3つ目は特に見落とされます。private registryのモジュールには、社内の命名規則やネットワーク構成がそのまま入っているためです。外部のモデルへ送ってよいかは、toolを開ける前に判断する話になります。差分そのものの読み方はterraform planの差分の読み方とinit・apply・destroyの安全手順にまとめました。MCPサーバーはレビューの材料を集める道具であって、レビューそのものを代行する道具ではありません。

よくある質問

導入検討でよく確認される点をまとめます。

Terraform MCP Serverは無料で使えますか？

サーバー自体はMPL-2.0のオープンソースで、Dockerイメージもソースも公開されています。費用が関係するのはHCP Terraform／Terraform Enterprise側で、terraform toolsetやregistry-private toolsetを使うにはそれらの契約とAPIトークンが必要です。公開レジストリだけを参照するregistry toolsetの範囲なら、契約もトークンも要らずに動きます。

TFE_TOKENを設定しないと使えませんか？

既定のregistry toolsetの9本は、TFE_TOKENなしで動作する対象です。公開レジストリのprovider検索、モジュール検索、Sentinelポリシー検索と、それぞれの詳細取得と最新版取得が該当します。private registryの4本と、HCP Terraformを操作する47本にはトークンが必要です。まずトークンなしで接続確認を済ませてから、必要になった段階で渡す順序を勧めます。

AWS Labs版とHashiCorp公式版のどちらを入れるべきですか？

AWS専業で、ローカルの terraform plan をAIに走らせたい、Checkovのスキャンも同じ流れで回したいならAWS Labs版です。マルチクラウドでprovider・モジュールの参照精度を上げたい、あるいはHCP Terraformのワークスペースとrunを扱いたいならHashiCorp公式版になります。目的が重ならないため、両方を登録して用途で呼び分ける構成も取れます。

terraform applyをAIに実行させられますか？

HashiCorp公式版にはCLIを実行するtoolがないため、ローカルでのapplyは行えません。可能なのはHCP Terraform／Terraform Enterprise側のrunを create_run や action_run で操作することで、これらはENABLE_TF_OPERATIONSをtrueにしない限り閉じています。適用の承認は既存のCI／PRフローに残し、MCPは調査と再実行の補助に留める設計が安全です。

Terraform Enterpriseの自ホスト環境でも使えますか？

使えます。TFE_ADDRESS にプロトコルを含めた自ホストのアドレスを指定してください。streamable-httpモードではこの値をクライアントから変更できず、サーバー側の環境変数だけで決まります。社内認証局の証明書で検証に失敗する場合は TFE_SKIP_TLS_VERIFY がありますが、トークンを平文経路に晒すことになるため、証明書を配布して解決するほうが筋の良い対処になります。

関連記事

• MCPとは？AIと外部ツールをつなぐ標準規格の仕組み・MCPサーバーの役割を解説：規格そのものの仕組みとサーバーの役割。
• IaCとは？Infrastructure as Codeの仕組み・メリットと導入判断を解説：宣言的な構成管理の考え方と導入判断。
• HCP Terraformとは？旧Terraform Cloud（名称変更）の機能・料金とHCPでの位置づけを解説：接続先となるSaaS側の機能と料金。
• terraform providerのバージョン制約とalias設計｜lockファイルの運用判断：版の固定方針とlockの運用。
• terraform planの差分の読み方｜init・apply・destroyの安全手順：差分の記号とサマリ行の読み順。