Terraform MCPサーバーの使い方 — ClaudeにIaCコードを書かせる

Terraform MCPサーバーはHashiCorp公式のMCPサーバーで、Terraform RegistryとHCP Terraform / Terraform EnterpriseのAPIをClaude Codeなどのクライアントに接続します。プロバイダーやモジュールのドキュメントをその場で検索し、Sentinelポリシーの要件を確認しながらHCLコードを書けるのが特徴です。

サーバーが提供するツールは大きく2系統に分かれます。Registry(公開情報)を検索する読み取り系ツールと、HCP Terraformのワークスペースを操作する実行系ツールです。本記事は前者を扱います。ワークスペースの作成・更新・削除、変数やタグの管理、Run(実行)の制御は別のツールセットになり、そちらの操作手順はTerraform MCPサーバーのワークスペース管理にまとめています。読み取り系だけで済むならトークン設定は不要ですが、実行系まで使う場合は先にそちらで権限設計を確認しておくと迷いません。

Terraform MCPサーバーとは

Terraform MCPサーバーとは、Terraform RegistryのProvider・Module・Sentinelポリシードキュメントと、HCP Terraform / Terraform EnterpriseのAPIをAIモデルから呼び出せるようにするHashiCorp公式サーバーです。Go言語で実装され、GitHub上でhashicorp/terraform-mcp-serverとして公開されています。

ローカルで動かすstdioトランスポートと、複数ユーザーで共有するstreamableHTTPトランスポートの両方に対応します。デフォルトはstdioで、ローカル開発や単発プロジェクトに向きます。センターで一元運用する場合はHTTPトランスポートを使い、組織ごとのトークンをヘッダー経由で渡す設計です。

なおHashiCorpのIBMによる買収に伴い、READMEの法的注記はIBMの名義になっています。開発自体はhashicorp組織のリポジトリで継続しており、開発元が変わったわけではありません。

Provider・Module・Policy検索ツールでできること

読み取り系のツールは3つのグループに分かれます。Provider toolsはAWS・Azure・Google Cloud等のプロバイダードキュメントを検索し、リソース設定のサンプルコードを取得します。Module toolsはTerraform Registryのコミュニティ・検証済みモジュールを検索します。Policy toolsはSentinelポリシー(ガバナンス・コンプライアンス要件を定義するHashiCorp独自の言語)のドキュメントを取得します。

これらのツールはAI側が自動で呼び出すので、手動での実行は不要です。「AWSのS3バケットをバージョニング有効で設定したい」のように具体的に聞くと、search_providersでドキュメントIDを絞り込み、get_provider_detailsで該当リソースの完全なコード例を取得します。プロバイダーやモジュールの正式なリソースアドレスを含めて質問すると、Registryツール経由の応答になりやすくなります。

実際の応答例 — Azureストレージアカウントの場合

公式ドキュメントには、GitHub CopilotのVS Code経由でTerraform MCPサーバーを使った実例が載っています。「azureプロバイダーでストレージバケットを設定したい」と聞くと、まずsearch_providersがazurermプロバイダーのstorage_account関連ドキュメントを検索し、続けてget_provider_detailsが該当ドキュメントIDの完全な内容を取得します。返るのは次のような、実際にRegistryへ登録されているサンプルコードです。

resource "azurerm_resource_group" "example" {
  name     = "example-resources"
  location = "West Europe"
}
 
resource "azurerm_storage_account" "example" {
  name                     = "storageaccountname"
  resource_group_name      = azurerm_resource_group.example.name
  location                 = azurerm_resource_group.example.location
  account_tier             = "Standard"
  account_replication_type = "GRS"
  tags = {
    environment = "staging"
  }
}

この応答はモデルやクライアントによって多少変わりますが、Registryに実在するドキュメントを根拠にしている点が、AIの内部知識だけで生成したコードとの違いです。プロバイダーのバージョンが変わって引数名が変更されていても、MCPサーバー経由なら最新のドキュメントを参照できます。

Claude Codeへの追加方法

# ローカル(stdio)トランスポート
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

Docker経由が公式の推奨経路です。イメージ内にGoバイナリが同梱されているため、Terraform CLI自体のインストールは不要です。Registryの検索だけならHCP Terraformのトークンも必須ではありません。

HCP TerraformやTerraform Enterpriseのプライベートレジストリ・ワークスペースにもアクセスする場合は、環境変数でトークンを渡します。

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

複数ユーザーで共有するstreamableHTTPモードにする場合は、サーバー起動時にTRANSPORT_MODE=streamable-httpを指定し、Claude Code側は--transport httpで接続します。

docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server
claude mcp add --transport http terraform http://localhost:8080/mcp

Docker以外にも、Goのビルド済みバイナリをソースからインストールする方法があります。go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latestでホストにインストールし、commandにパスを直接指定する構成です。コーポレートプロキシでTLS検査(Zscaler等)を使う環境では、証明書エラーが出ることがあります。対処はコンテナに社内CA証明書をマウントし、SSL_CERT_FILE環境変数で指すことです。

toolsetsで有効にするツールを絞る

デフォルトで有効なのはregistryツールセットのみです。HCP Terraformのワークスペース操作系ツール(terraformツールセット)は明示的に有効化しないと使えません。読み取り専用でRegistry検索だけに絞りたい場合は、既定のままで十分です。

# Registry検索のみ(既定)
terraform-mcp-server --toolsets=registry
 
# 個別ツール名で絞る
terraform-mcp-server --tools=search_providers,get_provider_details,search_modules

--toolsetsと--toolsは同時に指定できません。トップレベルのtoolsetはregistry(公開Registry検索)・registry-private(組織のプライベートレジストリ検索)・terraform(HCP Terraform / Terraform Enterprise操作)の3種類です。ツール数を絞ると、AIがツール選択で迷う場面が減り、意図しないHCP Terraform操作を防ぐ効果もあります。

ツールに加えて公式スタイルガイドも参照できる

ツール呼び出し以外に、Terraform MCPサーバーは静的な参照データを「リソース」として2つ公開しています。/terraform/style-guideは公式のTerraformスタイルガイド、/terraform/module-developmentはモジュール構成・プロバイダー設計・公開手順をまとめたガイドです。どちらもAIがコードを生成するときの規約として自動的に参照され、命名規則やディレクトリ構成が公式の慣習に沿いやすくなります。

これとは別に、パラメータ付きで動的に解決される「リソーステンプレート」も1つ用意されています。/terraform/providers/{namespace}/name/{name}/version/{version}という形式で、namespace(プロバイダーの発行元)・name(プロバイダー名)・version(バージョン)を指定すると、そのプロバイダーの該当バージョンのドキュメント一式を直接参照できます。get_provider_detailsツールが特定コンポーネントの本文を都度取得するのに対し、こちらはプロバイダー丸ごとのドキュメント参照を1つのURI形式で済ませたいときに使う経路です。

セキュリティ上の注意点

公式のセキュリティモデルは、次の5つを主な脅威として挙げています。ハルシネーション(AIが事実でない情報を生成すること)・プロンプトインジェクション・ツールポイズニング・Rug pull attack(承認後にツールの動作が悪意ある内容へ差し替わる攻撃)・Tool shadowing(別のツールになりすまして意図しない呼び出しを誘発する攻撃)の5種類です。Terraform MCPサーバー自体は静的なツール説明を使い、ユーザー入力の検証も実装していますが、インフラへの変更適用前に出力内容を人間が検証することを公式が明確に推奨しています。基盤となるAIモデル自体の脆弱性や、生成されたコードが実際にデプロイされた後のインフラ設定は、このサーバーの脅威モデルの対象外です。

信頼できないMCPクライアントやLLMと組み合わせて使わないことも公式の注記にあります。クエリ内容によっては、TerraformのデータがMCPクライアント側に渡るためです。

よくあるつまずき

「AWSのストレージを設定して」のような曖昧な質問だとRegistryツールが呼ばれない。AI側は一般的なTerraform設定の話であれば内部知識で回答することがあり、必ずしもMCPサーバー経由のドキュメントを参照するとは限りません。google_compute_diskのような具体的なリソース名や、Terraform CLIドキュメントで定義されたリソースアドレス形式を含めると、Registryツールが呼ばれやすくなります。

バージョン指定を省略するとlatestが使われる。特定バージョンのプロバイダーで動作確認したいときは、プロンプトにバージョン番号を明記しないと最新版のドキュメントが返ります。

HCP Terraformのワークスペース操作系ツールが動かない。terraformツールセットが有効になっていないか、TFE_TOKENが未設定のケースがほとんどです。読み取り専用のRegistry検索とワークスペース操作は別のトークン・別のツールセットで動く点を混同しないようにします。

まとめ

Terraform MCPサーバーのRegistry検索系ツールは、Provider・Module・Sentinelポリシーのドキュメントをその場で取得し、AIが最新かつ正確なHCLコードを生成する土台になります。Dockerでの導入は数分で終わり、HCP Terraformのトークンが無くても公開Registryの検索だけなら動きます。IaCのコードレビューやプロトタイピングでプロバイダーの正確な構文を確認したいチームに向きます。

一方でワークスペースの作成・削除、変数管理、Run制御といった実行系の操作は別のツールセットで、破壊的な操作には明示的な環境変数の有効化が必要です。MCPプロトコル自体の仕組みはMCPとは、権限設計の一般論はMCPセキュリティガイドを参照してください。