Terraform MCP Server

Terraform MCP Server

Terraform MCP Serverは、Terraform RegistryおよびHCP TerraformAPIとシームレスに統合するModel Context Protocol（MCP）サーバーであり、Infrastructure as Code（IaC）開発における高度な自動化と対話機能を実現します。

目次

機能

• デュアルトランスポートサポート: 設定可能なエンドポイントを備えたStdioおよびStreamableHTTPトランスポートの両方
• Terraform Registry統合: プロバイダー、モジュール、ポリシー向けのパブリックTerraform Registry APIとの直接統合
• HCP TerraformおよびTerraform Enterpriseサポート: 完全なワークスペース管理、組織/プロジェクト一覧、プライベートレジストリへのアクセス
• ワークスペース操作: 変数、タグ、ランの管理をサポートするワークスペースの作成、更新、削除
• ツール使用状況監視のためのOTelメトリクス: Streamable HTTPモードでツール呼び出し量、レイテンシ、失敗を追跡するためのオープンテレメトリーメーターとの統合。この機能を有効にすると、デフォルトのHTTPサーバーメトリクスも公開されます

セキュリティに関する注意: クエリによっては、MCPサーバーが特定のTerraformデータをMCPクライアントおよびLLMに公開する場合があります。信頼できないMCPクライアントまたはLLMとともにMCPサーバーを使用しないでください。

法的注意: 第三者のMCPクライアント/LLMの使用は、そのようなMCP/LLMの利用規約にのみ従うものとし、IBMはそのような第三者のツールの性能について責任を負いません。IBMは、第三者のMCPクライアント/LLMに対する一切の保証および責任を明示的に否認し、第三者のツールによって引き起こされた問題を解決するためのサポートを提供できない場合があります。

注意: MCPサーバーによって提供される出力および推奨事項は動的に生成され、クエリ、モデル、接続されたMCPクライアントによって異なる場合があります。ユーザーは、実装前にすべての出力/推奨事項を十分に確認し、組織のセキュリティベストプラクティス、コスト効率の目標、コンプライアンス要件に沿っていることを確認する必要があります。

前提条件

1. コンテナ化された環境でサーバーを使用するには、Dockerがインストールされ、実行されていることを確認してください。
2. Model Context Protocol（MCP）をサポートするAIアシスタントをインストールしてください。

コマンドラインオプション

環境変数:

# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--organization-allowlist <orgs-csv>] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

手順

MCPサーバーのデフォルトの手順はcmd/terraform-mcp-server/instructions.mdにあります。これらが組織のTerraformプラクティスに適していない場合、またはMCPサーバーが不正確な応答を生成している場合は、独自の手順に置き換えてコンテナまたはバイナリを再ビルドしてください。そのような手順の例はinstructions/example-mcp-instructions.mdにあります。

AGENTS.mdは、基本的にコーディングエージェント向けのREADMEとして機能します。AIコーディングエージェントがプロジェクトで作業するためのコンテキストと手順を提供する、専用の予測可能な場所です。1つのAGENTS.mdファイルがさまざまなコーディングエージェントで動作します。そのような手順の例はinstructions/example-AGENTS.mdにあり、使用するにはAGENTS.mdという名前のファイルをTerraform構成が配置されているディレクトリにコミットしてください。

インストール

Visual Studio Codeでの使用

VS Codeのユーザー設定（JSON）ファイルに次のJSONブロックを追加します。これを行うには、Ctrl + Shift + Pを押してPreferences: Open User Settings (JSON)と入力します。

VS CodeのエージェントモードドキュメントでのMCPサーバーツールの使用について詳しくは、こちらをご覧ください。

{
  "mcp": {
    "servers": {
      "terraform": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e", "TFE_TOKEN=${input:tfe_token}",
          "-e", "TFE_ADDRESS=${input:tfe_address}",
          "hashicorp/terraform-mcp-server:1.3.0"
        ]
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "tfe_token",
        "description": "Terraform API Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "tfe_address",
        "description": "Terraform Address",
        "password": false
      }
    ]
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "hashicorp/terraform-mcp-server:0.2.3"
        ]
      }
    }
  }
}

オプションとして、ワークスペース内の.vscode/mcp.jsonというファイルに同様の例（つまり、mcpキーなし）を追加できます。これにより、設定を他のユーザーと共有できます。

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_TOKEN=${input:tfe_token}",
        "-e", "TFE_ADDRESS=${input:tfe_address}",
        "hashicorp/terraform-mcp-server:1.3.0"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Cursorでの使用

Cursor設定（~/.cursor/mcp.json）または設定 → Cursor設定 → MCPにこれを追加します:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.3.0"
      ]
    }
  }
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Claude Desktop / Amazon Q Developer / Kiro CLI での使用

Claude Desktop での MCP サーバーツールの使用については、ユーザードキュメントを参照してください。Amazon Q Developer および Kiro CLI での MCP サーバーの使用についても詳しく説明しています。

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.3.0"
      ]
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Claude Code での使用

Claude Code での MCP サーバーツールの使用と追加については、ユーザードキュメントを参照してください。

• ローカル (stdio) トランスポート

claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

• リモート (streamable-http) トランスポート

# Run server (example)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp

Codex CLI での使用

Codex CLI での MCP サーバーツールの使用と追加については、ユーザードキュメントを参照してください。

注: 認証済みの HCP Terraform または Terraform Enterprise ツールを使用するには、Docker コマンドに TFE_ADDRESS と TFE_TOKEN を追加してください。

• ローカル (stdio) トランスポート

codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

• リモート (streamable-http) トランスポート

# Run server (example)
docker run --rm -p 127.0.0.1:8080:8080 -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Codex
codex mcp add terraform --url http://localhost:8080/mcp

Gemini 拡張機能での使用

セキュリティ上の理由から、認証情報をハードコーディングすることは避け、HCP Terraform または Terraform Enterprise の認証情報を保存するために ~/.gemini/.env（~ はホームディレクトリまたはプロジェクトディレクトリ）を作成または更新してください。

# ~/.gemini/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

拡張機能をインストールして Gemini を実行します。

gemini extensions install https://github.com/hashicorp/terraform-mcp-server
gemini

Bob IDE / Shell での使用

Bob IDE または Shell での MCP サーバーツールの使用と追加については、Bob での MCP の使用を参照してください。

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.3.0"
      ],
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ],
      "disabled": false
    }
  }
}

Kubernetes (Helm)

Kubernetes にサーバーをデプロイするための Helm チャートは、helm/terraform-mcp-server で入手できます。

ソースからのインストール

最新のリリースバージョンを使用する場合:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest

main ブランチを使用する場合:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server",
        "env": {
          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"
        },
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server"
      }
    }
  }
}

Docker イメージのローカルビルド

サーバーを使用する前に、Docker イメージをローカルでビルドする必要があります:

1. リポジトリをクローンします:

git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server

2. Docker イメージをビルドします:

make docker-build

3. これにより、以下の設定で使用できるローカルの Docker イメージが作成されます。

# Run in stdio mode
docker run -i --rm terraform-mcp-server:dev

# Run in streamable-http mode
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# Filter tools (optional)
docker run -i --rm terraform-mcp-server:dev --toolsets=registry,terraform
docker run -i --rm terraform-mcp-server:dev --tools=search_provider_docs,get_provider_details

注: Docker で実行する場合、コンテナ外部からの接続を許可するために TRANSPORT_HOST=0.0.0.0 を設定する必要があります。

4. (任意) HTTP モードで接続をテストします

# Test the connection
curl http://localhost:8080/health

5. AI アシスタントで次のように使用できます:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

利用可能なツール

利用可能なツールはこちらをご覧ください :link:

利用可能なリソース

利用可能なリソースはこちらをご覧ください :link:

利用可能なメトリクス

2 種類のメトリクスが収集されます。 まず、HTTP サーバーの標準メトリクスは、HTTP mux を otelhttp.NewHandler(...) でラップすることで追加されます。これにより、以下が出力されます:

1. http.server.request.body.size
2. http.server.response.body.size
3. http.server.request.duration

次に、MCP サーバーは、MCP フック（BeforeCallTool / AfterCallTool）を使用して、ツール実行に関するカスタムツールメトリクスを記録します。これにより、以下が出力されます:

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

ツールフィルタリング

--toolsets（グループ）または --tools（個別）を使用して、利用可能なツールを制御します:

# Enable tool groups (default: registry)
terraform-mcp-server --toolsets=registry,terraform

# Enable specific tools only
terraform-mcp-server --tools=search_provider_docs,get_provider_details,list_workspaces

利用可能なツールセット: registry、registry-private、terraform、all、default。個別のツール名については pkg/toolsets/mapping.go を参照してください。両方のフラグを同時に使用することはできません。

トランスポートサポート

Terraform MCP Server は複数のトランスポートプロトコルをサポートしています:

1. Stdio トランスポート（デフォルト）

JSON-RPC メッセージを使用した標準入出力通信。ローカル開発や MCP クライアントとの直接統合に最適です。

2. StreamableHTTP トランスポート

直接の HTTP リクエストと Server-Sent Events (SSE) ストリームの両方をサポートする最新の HTTP ベースのトランスポート。リモート/分散セットアップに推奨されるトランスポートです。

特徴:

• エンドポイント: http://{hostname}:8080/mcp
• ヘルスチェック: http://{hostname}:8080/health
• 環境設定: 有効にするには TRANSPORT_MODE=http または TRANSPORT_PORT=8080 を設定します
• 組織の許可リスト: 許可された HCP Terraform 組織名の CSV リストを MCP_ORGANIZATION_ALLOWLIST または --organization-allowlist に設定します

セッションモード

Terraform MCP Server は、StreamableHTTP トランスポート使用時に 2 つのセッションモードをサポートしています:

• ステートフルモード（デフォルト）: リクエスト間でセッション状態を維持し、コンテキストを認識した操作を可能にします。
• ステートレスモード: 各リクエストはセッション状態を維持せずに独立して処理されます。高可用性デプロイメントやロードバランサーを使用する場合に役立ちます。

ステートレスモードを有効にするには、環境変数を設定します:

export MCP_SESSION_MODE=stateless

集中デプロイメントのためのトークンパススルー

MCP サーバーを複数ユーザー向けに集中的に（StreamableHTTP モードで）実行する場合、各ユーザーは HTTP ヘッダーを介して独自の Terraform トークンを渡すことができ、RBAC の強制が可能になります。これにより、単一のサーバーインスタンスで異なる権限を持つ複数のユーザーにサービスを提供できます。

MCP_ORGANIZATION_ALLOWLIST または --organization-allowlist が設定されている場合、許可リストは HCP Terraform 組織名の CSV リストである必要があります。サーバーは Authorization: Bearer <token> を必須とし、そのトークンが CSV 許可リスト内の少なくとも 1 つの組織にアクセスできない限り、リクエストを拒否します。リクエストに TFE_TOKEN ヘッダーも含まれている場合、ベアラートークンが優先され、許可リストによって検証されたトークンが Terraform API リクエストに使用されるトークンであることが保証されます。組織名のマッチングは大文字と小文字を区別しません。設定された CSV 値がゼロ個の組織名に解析される場合、サーバーは不正な組織許可リストエラーで終了します。

クライアント IP 転送

MCP サーバーをプロキシまたはロードバランサーの背後で集中的に実行する場合、X-Forwarded-For ヘッダーを介して発信元クライアントの IP を HCP Terraform / TFE に転送できます。これはデフォルトでオフになっており、MCP_FORWARD_CLIENT_IP=true で有効にする必要があります。

有効にすると、サーバーは MCP_REMOTE_IP_METHOD に従ってクライアント IP を取得します:

信頼モデル

X-Forwarded-For と X-Real-IP はクライアントと中間プロキシによって設定されるため、サーバーの前にある信頼できるプロキシがそれらを上書きしない限り、スプーフィングされる可能性があります。このため、デフォルトは RemoteAddr であり、サーバーが直接接続されているピアのみを信頼します。サーバーがこれらのヘッダーを設定する管理下のプロキシの背後にある場合にのみ、X-Real-IP または X-Forwarded-For を有効にしてください。

信頼されたホップ

X-Forwarded-For を使用する場合、MCP_XFF_TRUSTED_HOPS はサーバーとインターネットの間で運用するプロキシの数です。各プロキシはリクエストを受け取ったアドレスを追加するため、ホップはチェーンの右から数えられ、右端のエントリはサーバーに最も近いプロキシによって設定されます。サーバーはその数の信頼されたエントリをスキップし、左隣のエントリを取得します。

たとえば、MCP_XFF_TRUSTED_HOPS=1 とヘッダー 200.1.2.3, 10.1.1.10 の場合、サーバーは 200.1.2.3 を選択します。MCP_XFF_TRUSTED_HOPS=2 と 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1 の場合、200.1.2.3 を選択します。ホップ数がエントリ数より大きい場合、または選択されたエントリが有効な IP でない場合、サーバーは RemoteAddr にフォールバックします。

ホップ数を低く設定しすぎるとクライアント提供の値を信頼することになり、高く設定しすぎると自社インフラストラクチャのさらに奥のアドレスを信頼することになります。運用するプロキシの正確な数に設定してください。

制限事項

• サーバーはリクエストの最初の X-Forwarded-For ヘッダーのみを読み取ります。リクエストが複数の X-Forwarded-For ヘッダーを運ぶことは有効ですが、Go の標準ライブラリは最初のもののみを返し、サーバーはそれらを結合しません。プロキシチェーンが複数のヘッダーを出力する場合は、単一の結合された X-Forwarded-For ヘッダーを出力するように設定してください。
• IPv4 アドレスと IPv6 アドレスの両方がサポートされています。有効な IP ではない値は拒否され、サーバーは RemoteAddr にフォールバックします。

以前のバージョンからの移行

以前のバージョンでは、ヘッダーが存在する場合、設定なしで左端の X-Forwarded-For 値を使用していました。これは、左端の値が最もスプーフィングされやすいため、安全ではありませんでした。デフォルトは現在 RemoteAddr です。プロキシの背後でサーバーを実行し、X-Forwarded-For が HCP Terraform / TFE に転送されることに依存している場合は、MCP_REMOTE_IP_METHOD=X-Forwarded-For と MCP_XFF_TRUSTED_HOPS を運用するプロキシの数に設定してください。

サポートされているヘッダー

例: curl

# Using TFE_TOKEN header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "TFE_TOKEN: your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

# Using Authorization Bearer header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

セキュリティに関する考慮事項

• TFE_ADDRESS はクライアントが設定できません。 streamable-http モードでは、Terraform アドレスはサーバー側の TFE_ADDRESS 環境変数（またはデフォルト）からのみ取得されます。HTTP ヘッダーまたはクエリパラメータを介して TFE_ADDRESS を設定しようとするリクエストは、403 で拒否されます。これにより、クライアントがリクエストと Authorization トークンを悪意のあるサーバーにリダイレクトすることを防ぎます。
• ホステッドデプロイメントの識別: TF_MCP_SHARED_SECRET を設定すると、その値がすべての HCP Terraform / TFE リクエストで X-Tf-Mcp-Secret ヘッダーとして送信され、バックエンドが既知のホステッドデプロイメントからのリクエストを識別できるようになります（例: IP 許可リストの適用）。これはヘッダーで送信される静的シークレットであるため、TLS 経由でのみ使用し、値を認証情報として扱ってください。
• クエリパラメータでトークンを渡さないでください - サーバーはそのようなリクエストを 400 エラーで拒否します。
• 集中デプロイメントでは、転送中のトークンを保護するために常に TLS（MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE）を使用してください。
• 接続できるクライアントを制限するには、MCP_ALLOWED_ORIGINS を設定してください。

集中デプロイメントの例

# Start server centrally (no token set server-side)
docker run -p 8080:8080 \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e TFE_ADDRESS=https://tfe.company.com \
  -e MCP_TLS_CERT_FILE=/certs/server.pem \
  -e MCP_TLS_KEY_FILE=/certs/server-key.pem \
  -e MCP_ALLOWED_ORIGINS=https://ide.company.com \
  -e MCP_ORGANIZATION_ALLOWLIST=team-alpha,team-beta \
  -v /path/to/certs:/certs \
  hashicorp/terraform-mcp-server:1.3.0

ユーザーはその後、個々のトークンをヘッダーを介して渡して接続し、ユーザーごとの RBAC 強制が可能になります。

トラブルシューティング

コーポレートプロキシ / TLS 検査（Zscaler など）

Zscaler Internet Access などの TLS 検査を実行するコーポレートプロキシの背後にいる場合、証明書エラーが発生する可能性があります:

tls: failed to verify certificate: x509: certificate signed by unknown authority

解決策: コーポレート CA 証明書をコンテナにマウントします:

docker run -i --rm \
  -v /path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem \
  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
  hashicorp/terraform-mcp-server:1.3.0

MCP クライアント設定の場合:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem",
        "-e", "SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem",
        "-e", "TFE_TOKEN=<>",
        "hashicorp/terraform-mcp-server:1.3.0"
      ]
    }
  }
}

代替案: バイナリを直接実行する

環境で Docker が許可されていない場合は、サーバーバイナリを直接インストールして実行できます。これにより、システムの証明書ストアが使用されます:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
terraform-mcp-server stdio

開発

前提条件

• Go（go.mod ファイルで特定のバージョンを確認してください）
• Docker（任意、コンテナビルド用）

利用可能な Make コマンド

コントリビューション

1. リポジトリをフォークする
2. フィーチャーブランチを作成する
3. 変更を加える
4. テストを実行する
5. プルリクエストを送信する

ライセンス

このプロジェクトはMPL-2.0オープンソースライセンスの条件に基づいてライセンスされています。完全な条件については、LICENSEファイルを参照してください。

セキュリティ

セキュリティの問題については、security@hashicorp.comまでご連絡いただくか、セキュリティポリシーに従ってください。

サポート

バグ報告や機能リクエストについては、GitHubでイシューを開いてください。

一般的な質問や議論については、GitHubディスカッションを開いてください。