Terraform CWD MCP Server

@yawlabs/terraform-cwd-mcp

ワンクリックでローカルの Yaw MCP 設定に追加され、すべての Yaw Terminal セッションで利用できるようになります。または、以下の手順で手動インストールしてください。

この Terraform 作業ディレクトリで実際に正しい情報を確認できます。.terraform.lock.hcl で固定された正確なプロバイダー スキーマ（コーディングエージェントが、存在しない、削除済み、または読み取り専用の引数を書かないようにするための情報）、保存済みのプラン、（秘匿化された）状態、ローカルおよびインストール済みのモジュール、そしてプロバイダーをアップグレードした場合に何が壊れるかを確認できます。 HashiCorp の terraform-mcp-server を置き換えるのではなく、補完するものです。あちらのサーバーは Terraform Registry のドキュメントを参照して回答しますが、そこに記載されているのは最新のプロバイダーリリースです。一方、こちらはルートモジュールで terraform providers schema -json を実行し、実際に固定したバージョンについて回答します。両方を実行してください。

Yaw Labs が開発・保守しています。

このサーバーを選ぶ理由

ロックファイルには hashicorp/aws 5.31.0 と記載されていますが、Registry のドキュメント（およびモデルのトレーニングデータ）は、その後またはそれ以前のバージョンの情報を示しています。その結果、エージェントは固定したバージョンより後に追加された引数、以前のバージョンで削除された引数、あるいは computed 専用で設定できない引数を書いてしまいます。terraform validate で検出できるのは、コードが書かれた後です。このサーバーを使えば、エージェントはコードを書く前に確認できます。

• 最新ではなく、固定済みの情報 -- 信頼できる情報源は、ルートモジュールで実行した terraform providers schema -json です。バージョンは .terraform.lock.hcl から読み取ります。
• 読み取り専用で、init は実行しません -- terraform init は実行しません（ダウンロード、バックエンドへの接続、ロックファイルの書き換えはありません）。初期化されていないディレクトリでは、実行すべき内容を示す実用的なエラーが表示されます。
• ロックファイルごとにキャッシュ -- ダンプはメモリとディスクにキャッシュされ、ルートパスとロックファイルの内容をキーとして使用します。そのため、プロバイダーをアップグレードするとキャッシュは自動的に無効になります。AWS プロバイダーのスキーマは数十 MB ありますが、ロックファイルが変更されるたびに一度だけダンプされ、質問ごとにダンプされることはありません。
• 簡潔な回答 -- tf_get_schema は、モデルに生の JSON を渡す代わりに、1 つの型をインデント付きのコンパクトな概要として表示します。required／optional／optional+computed／computed (read-only)、[deprecated]、[sensitive]、[write_only] のフラグも表示されます。
• クロスプラットフォーム対応 -- macOS、Linux、Windows に対応しています。Terraform はシェルを介さず直接起動し、出力はストリーミングされるため、バッファーの上限はありません。

ツール

ツール	機能
tf_list_providers	ルートモジュール内のプロバイダーと、固定されたバージョン、リソース／データ／エフェメラルの件数を表示します。最初に呼び出してください。
tf_search_types	種類ごとに、部分文字列（s3_bucket）を含む型名を検索します。
tf_get_schema	固定バージョンにおける、1つの型のすべての引数とネストされたブロックを、モードとフラグとともに表示します。ブロックの作成または編集前に使用してください。
tf_check_arguments	ドット区切りのパス（["bucket", "versioning.enabled"]）を検証し、各パスについて ok、ok (block)（どちらも [deprecated] が付く場合あり）、READ-ONLY (computed)、'<x>' is an attribute, not a block、または UNKNOWN を返します。
tf_summarize_plan	保存済みプラン（plan_file：terraform plan -out によるバイナリ、またはプラン JSON）またはプラン JSON テキスト（plan_json。例：公式サーバーから取得した HCP 実行のプラン）を要約します。最初に削除と置換、および各置換を強制する属性を示し、続けて更新（変更されたパス）、作成、インポート、移動、追跡対象からの除外、ドリフト、延期された変更、出力を表示します。Terraform 独自の Plan: 件数と、moved ブロックが必要な名前変更を示す破棄警告も表示します。値は一切表示しません。
tf_module_interface	ルート、ローカルモジュールのパス、またはアドレスで指定したインストール済みモジュール（module.network、ダウンロード済みのレジストリ／Git モジュールを含む）の変数（型式を正確に表示し、必須／任意、デフォルト、[sensitive]／[not nullable]／[ephemeral]、検証件数を表示）、出力、モジュール呼び出しを表示します。未インストールまたは古いモジュール呼び出しにはフラグを付けます。サブプロセスは使用しません。
tf_state_addresses	現在のステートにあるリソースインスタンスのアドレス（terraform state list）を、部分文字列フィルターと id 検索とともに表示します。
tf_show_resource	ステート（terraform show -json）から、1つのインスタンスの属性値を表示します。機密値はマスキングし、何がどの理由で非表示になったかをフッターに記載します。
tf_upgrade_impact	固定されたプロバイダーを特定のバージョンに移行した場合の影響を表示します。対象バージョンで削除、読み取り専用化、型変更、新たに必須化、または非推奨化される、設定（ルート＋インストール済みモジュール）内の引数、ネストされたブロック、属性参照、provider ブロック引数を示します。移行を妨げるバージョン制約も表示し、一時コピーに対する terraform validate で確認します。

すべてのツールで、オプションの dir（ルートモジュール）を指定できます。kind は resource（デフォルト）、data、または ephemeral です。

HashiCorp 公式サーバーとの役割分担。 固定したバージョンでの引数の有効性と、このディレクトリのプラン、ステート、モジュールの内容については、このサーバーが優先されます。使用方法のドキュメント、最新バージョン、公開レジストリモジュール、HCP/TFE 実行については、公式サーバーが優先されます。HCP 実行のプランを扱うには、そこでプラン ID（get_run_details）を取得し、get_plan_json_output(plan_id) でプランを取得して、JSON を plan_json として tf_summarize_plan に渡してください（これらのツールでは、公式サーバーの terraform ツールセットと TFE_TOKEN が必要です）。

読み取り専用の範囲とネットワークへの接続

• 書き込みは行いません： ルートモジュール、その .terraform/、ロックファイル、state。ここでは terraform init を実行しません。
• State ツール（tf_state_addresses、tf_show_resource）は、ロックもリフレッシュも行わない terraform state list ／ terraform show -json を実行します。リモートバックエンドを使用している場合は、MCP サーバーが MCP クライアントから継承した認証情報を使って、S3／GCS／HCP から読み取ります。存在しない非デフォルトのワークスペースを選択すると Terraform が作成してしまうため（s3 バックエンドは空の state を書き込みます）、サーバーは先に terraform workspace list を確認し、作成を拒否します。
• tf_upgrade_impact は、使い捨ての一時ディレクトリで terraform init を実行し、対象プロバイダーのバージョンをプラグインキャッシュ（TERRAFORM_CWD_MCP_PLUGIN_CACHE、それ以外の場合は TF_PLUGIN_CACHE_DIR、それもない場合は <cache>/plugins）にダウンロードします。次に、すでにあるパッケージへのリンクを .terraform/providers に含む、設定の一時コピーに対して terraform validate を実行します。state と *.tfvars はコピーされません。プラグインキャッシュは並行インストールに対応していないため、呼び出しは直列化されます。
• 秘匿化（tf_show_resource）：Terraform のセンシティブマーカーに加え、state 内のどこかにあるマーク済みの値と等しい（またはその値を含む）文字列、シークレットらしいキー（password、api_token、client_secret など。ただし password_length や secret_arn は除く）配下の値、シークレットの形式に一致する文字列（秘密鍵、JWT、GitHub／GitLab／Slack／npm のトークン。URL のパスワードは該当箇所でマスクされます）を秘匿化します。「センシティブな値を表示」する切り替え機能は意図的に設けていません。Terraform 自身が表示する、マークされていない派生値（センシティブなファイルの content_md5 など）は出力されます。
• すべての Terraform 子プロセスに CHECKPOINT_DISABLE=1 が設定されるため、バージョン確認のために外部へ接続することはありません。

tf_summarize_plan の出力例（実際のプランの抜粋）：

plan (terraform 1.15.7, format 1.2): applyable, complete
totals: 1 delete, 5 replace, 1 update, 1 create, 0 read, 1 import, 1 move, 1 forget, 0 unchanged (terraform: 1 to import, 6 to add, 1 to change, 6 to destroy)
DELETE (1)
  - null_resource.gone (not in configuration)
REPLACE (5)
  -/+ local_sensitive_file.sf delete-then-create; forced by: content [sensitive]
  +/- random_string.cbd create-before-destroy; forced by: keepers
  ...
UPDATE (1)
  ~ terraform_data.cfg: input.version, output (known after apply)
WARNING: 6 object(s) will be destroyed (1 delete, 5 replace). 1 moved block(s) applied; none covers these.

tf_upgrade_impact の出力例（実際の validate 実行結果）：

upgrade hashicorp/random 2.3.1 -> 3.6.3 (major) for /work/infra
constraints: root pins 2.3.1 as local name rnd (change it to allow 3.6.3)
used types: resource random_password, random_id
affected arguments (2):
  random_password.p.number (main.tf:18): DEPRECATED in 3.6.3
  reads random_id.i.b64 (main.tf:36): REMOVED in 3.6.3
validate on a temp copy, 3.6.3 vs 2.3.1: 1 new error, 1 new warning, 1 warning resolved
  error main.tf:36: Unsupported attribute - This object has no argument, nested block, or exported attribute named "b64".
  warning main.tf:18 random_password.p: Attribute Deprecated - **NOTE**: This is deprecated, use `numeric` instead.
verdict: BREAKING (1 error after upgrade)

tf_get_schema の出力例：

resource random_password (registry.terraform.io/hashicorp/random 3.9.1)
  bcrypt_hash: string computed (read-only) [sensitive] - A bcrypt hash of the generated random password. ...
  keepers: ["map","string"] optional - Arbitrary map of values that, when changed, will trigger recreation of resource. ...
  length: number required - The length of the password desired. ...
  number: bool optional+computed [deprecated] - Include numeric characters in the result. ...
  result: string computed (read-only) [sensitive] - The generated random password.

クイックスタート

1. ルートモジュールを一度だけ初期化します（サーバーではなく、あなたが実行します）：

terraform init -backend=false

-backend=false で十分です。スキーマに必要なのはプロバイダーだけで、state は不要です。

2. サーバーを追加します。 ルートモジュールから Claude Code を使う場合：

# macOS / Linux / WSL
claude mcp add terraform-cwd -- npx -y @yawlabs/terraform-cwd-mcp@latest

# Windows
claude mcp add terraform-cwd -- cmd /c npx -y @yawlabs/terraform-cwd-mcp@latest

または、ルートモジュールの .mcp.json に追加します（あるいは任意の場所に置き、TERRAFORM_CWD_MCP_DIR を設定します）：

macOS／Linux／WSL：

{
  "mcpServers": {
    "terraform-cwd": {
      "command": "npx",
      "args": ["-y", "@yawlabs/terraform-cwd-mcp@latest"]
    }
  }
}

Windows：

{
  "mcpServers": {
    "terraform-cwd": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/terraform-cwd-mcp@latest"]
    }
  }
}

Windows で追加の手順が必要なのはなぜですか？ Node 20 以降では、child_process.spawn から .cmd ファイル（Windows での npx が該当します）を直接実行できません。cmd /c でラップするのが標準的な回避策です。

3. MCP クライアントを再起動し、たとえば次のように尋ねます：「バージョン付きの S3 バケットを追加してください。まず、引数が固定された AWS プロバイダーに適合するか確認してください。」

エージェントに使用を指示する

プロジェクトから指示すると、エージェントはサーバーを安定して利用できます。ルートモジュールの CLAUDE.md（または AGENTS.md）に次の内容を貼り付けてください：

## Terraform provider schemas

This repo pins provider versions in `.terraform.lock.hcl`; registry docs and your
training data describe other versions. Use the terraform-cwd MCP server:

- Call `tf_list_providers` once per session to see the pinned versions.
- Before writing or editing any `resource`, `data` or `ephemeral` block, call
  `tf_get_schema` for that type.
- Call `tf_check_arguments` with every argument path you set (dotted for nested
  blocks, e.g. `versioning.enabled`). Never use an argument it reports as
  `UNKNOWN` or `READ-ONLY (computed)`; replace a `[deprecated]` one if the
  schema offers an alternative.
- Before calling a module, read its inputs with `tf_module_interface`.
- After `terraform plan -out=tfplan`, review it with `tf_summarize_plan`
  (plan_file: tfplan) and call out every DELETE and REPLACE.
- Before bumping a provider version, run `tf_upgrade_impact`.

相性のよいツール

HashiCorp の terraform-mcp-server

hashicorp/terraform-mcp-server はレジストリと HCP に関する質問に答えます。一方、このサーバーは作業ディレクトリ内の実際の状態に答えます。両方を実行してください。役割は重複していません。回答が食い違う場合、どちらを優先するかは次の表のとおりです。

質問	情報源
ピン留めしているプロバイダーのバージョンで、引数 X は有効ですか？	terraform-cwd-mcp
vN にアップグレードすると、使用中のどの引数が機能しなくなりますか？	terraform-cwd-mcp (tf_upgrade_impact)
この保存済みプラン、ステート、またはローカル／インストール済みモジュールには何が含まれていますか？	terraform-cwd-mcp
リソース X はどのように使うことを想定されていますか？ドキュメントや例には何が書かれていますか？	terraform-mcp-server
最新のプロバイダーまたはモジュールのバージョンは何ですか？	terraform-mcp-server
使用すべき公開レジストリモジュールはどれですか？	terraform-mcp-server
HCP Terraform／TFE のワークスペースと実行	terraform-mcp-server
HCP の実行プラン	terraform-mcp-server が取得します（get_run_details -> プラン ID -> get_plan_json_output(plan_id)）。tf_summarize_plan がそれを要約します（plan_json）

公式サーバーは、デフォルトでは registry ツールセットのみで起動します。HCP／TFE に関する行の機能を使うには、--toolsets=registry,terraform（または all）と TFE_TOKEN を指定して起動する必要があります。ドキュメント検索ツールは v1.3.1 以降の search_provider_docs です（それ以前は search_providers で、これは破壊的変更を伴う名称変更です）。ツール名で許可リストを設定する場合は、この点に注意してください。

Yaw Mode のスキル

Yaw Terminal の Yaw Mode には、両方のサーバーを操作し、どちらかが利用できない場合も適切に機能を縮退させ、terraform plan で停止する4つのスキルが付属しています（apply や destroy は実行しません）。

• /yaw-tf -- 日常的な作成／編集／修正：各引数をピン留めされたスキーマと照合してから、fmt、validate、plan を実行して要約します。詳細な作業は以下の3つに引き継ぎます。
• /yaw-tf-refactor -- 名前変更、モジュールの移動、moved／import／removed ブロックを使ったインポートに対応します。プランで destroy と replace がゼロと確認できた場合にのみ完了します。
• /yaw-tf-plan-review -- ローカルの保存済みプランまたは HCP の実行に対する go／no-go チェックリストです。まず destroy を確認し、次に checkov／trivy と、IAM、ネットワーク、暗号化に関する注意点を確認します。
• /yaw-tf-upgrade -- プロバイダーのバージョン更新：最新バージョンを確認し、実際に使用している引数を対象に tf_upgrade_impact を実行してから、アップグレードガイドを確認し、編集、バージョンの再ピン留め、validate、plan を行います。

設定

すべて任意です。

環境変数	デフォルト	用途
TERRAFORM_CWD_MCP_DIR	サーバーの作業ディレクトリ	ツール呼び出しで dir が渡されない場合に使用するルートモジュールです。
TERRAFORM_CWD_MCP_CACHE	~/.cache/terraform-cwd-mcp	スキーマダンプ（<key>.json）のキャッシュ先です。いつでも安全に削除できます。
TERRAFORM_CWD_MCP_BINARY	terraform	実行するバイナリです。フルパスや、OpenTofu 用の tofu を指定できます（providers schema -json の出力は同じです）。
TERRAFORM_CWD_MCP_TIMEOUT_MS	300000	この時間が経過した後、Terraform コマンド（スキーマダンプ、状態の読み取り、ターゲットの初期化、検証）を終了します。
TERRAFORM_CWD_MCP_PLUGIN_CACHE	TF_PLUGIN_CACHE_DIR。未設定の場合は <cache>/plugins	tf_upgrade_impact がダウンロードしたプロバイダーパッケージを保存する場所です。

ランタイム（oam または Node）：

terraform-cwd-mcp コマンドは、使用可能な oam が見つかった場合はそれを優先し、見つからない場合は Node で実行します。0.19.0 より古い oam 上では実行されません。

環境変数	デフォルト	用途
TERRAFORM_CWD_MCP_RUNTIME	auto	auto：0.19.0 以降の最新の oam を使用し、該当するものがなければ Node を使用します。oam：oam を使用し、エラーが発生した場合は終了します。node：常に Node を使用します。oam でのみ問題が発生する場合の回避策です。
OAM_BIN	（未設定）	使用する oam バイナリのパスです。未設定の場合、ランチャーは OAM_INSTALL_DIR、インストール先（~/.oam/bin および Windows の %LOCALAPPDATA%\oam\bin）、PATH を確認し、最新のものを使用します。

古い oam は oam self-update で更新できます。デフォルトでサーバーを oam 上で実行する Yaw MCP では、yaw-mcp set <namespace> runtime=node を実行すると、このサーバーは Node に切り替わります。--permission サンドボックスオプションはありません。このサーバーは terraform を起動し、呼び出しで指定された任意のディレクトリを読み取るため、制限付きで許可できるものがないためです。

要件

• Node.js 20+
• PATH 上の Terraform（または OpenTofu）。terraform providers schema -json に対応するバージョンが必要です（0.12+。エフェメラルリソースには 1.10+ が必要です）。
• ルートまたはローカルパスを対象とする tf_module_interface と、プラン JSON を使用する tf_summarize_plan を除くすべてのツールで、初期化済みのルートモジュール（.terraform/ と .terraform.lock.hcl が存在すること）
• 状態ツール：バックエンドを初期化し（terraform init。-backend=false は使用しません）、認証情報をサーバーの環境に設定してください。
• tf_upgrade_impact：ターゲットバージョンを初めて要求する際にレジストリへのアクセスが必要です（そのバージョンでの以降の実行はオフラインで行えます）。
• <dir>/.terraform にある .terraform/：TF_DATA_DIR は適用されません。

貢献

git clone https://github.com/YawLabs/terraform-cwd-mcp.git
cd terraform-cwd-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsup bundle + declarations
npm test           # Vitest (the integration test runs only when terraform is on PATH)
npm run typecheck  # oam check . when oam is installed, else tsc --noEmit
npm run check:oam-floor  # the oam floor agrees across the repo and matches the latest oam release

リリースプロセスを含む全ワークフローについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT