Terraform MCP Server

Terraform MCP Server

Terraform MCP Serverは、Model Context Protocol (MCP) サーバーであり、Terraform Registry APIとのシームレスな統合を提供し、Infrastructure as Code (IaC) 開発における高度な自動化とインタラクション機能を実現します。

機能

• デュアルトランスポートサポート: 設定可能なエンドポイントを持つStdioおよびStreamableHTTPトランスポートの両方をサポート
• Terraform Registry統合: プロバイダー、モジュール、ポリシー向けのパブリックTerraform Registry APIとの直接統合
• HCP Terraform & Terraform Enterpriseサポート: 完全なワークスペース管理、組織/プロジェクトの一覧表示、プライベートレジストリアクセス
• ワークスペース操作: 変数、タグ、実行管理をサポートするワークスペースの作成、更新、削除
• ツール使用状況を監視するOTelメトリクス: Streamable HTTPモードでのツール呼び出し量、レイテンシ、障害を追跡するためのOpenTelemetryメーターとの統合。この機能が有効な場合、デフォルトの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 にあります。これを使用するには、Terraform設定が存在するディレクトリに AGENTS.md という名前のファイルをコミットしてください。

インストール

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.1.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.1.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）またはSettings → Cursor Settings → 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.1.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.1.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

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サーバーツールの使用と追加に関する詳細は、Using MCP in Bob をご覧ください。

{
  "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.1.0"
      ],
      "disabled": false
    }
  }
}

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

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

最新のリリースバージョンを使用します。

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

メインブランチを使用します。

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_providers,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 muxをotelhttp.NewHandler(...)でラップすることにより、標準のHTTPサーバーメトリクスが追加されます。これにより以下が出力されます。

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_providers,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 を設定して有効化
• 組織許可リスト: MCP_ORGANIZATION_ALLOWLIST または --organization-allowlist を、許可する HCP Terraform 組織名の CSV リストに設定

セッションモード

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

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

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

export MCP_SESSION_MODE=stateless

集中デプロイメント向けトークンパススルー

MCP サーバーを複数ユーザー向けに中央で (StreamableHTTP モードで) 実行する場合、各ユーザーは RBAC 適用のために HTTP ヘッダー経由で自身の Terraform トークンを渡すことができます。これにより、単一のサーバーインスタンスで異なる権限を持つ複数のユーザーにサービスを提供できます。

MCP_ORGANIZATION_ALLOWLIST または --organization-allowlist が設定されている場合、許可リストは HCP Terraform 組織名の CSV リストである必要があります。サーバーは Authorization: Bearer <token> を要求し、そのトークンが CSV 許可リスト内の少なくとも 1 つの組織にアクセスできない限りリクエストを拒否します。リクエストに TFE_TOKEN ヘッダーも含まれている場合、Bearer トークンが優先されるため、許可リストによって検証されたトークンが 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 トークンを悪意のあるサーバーにリダイレクトすることを防ぎます。
• クエリパラメータでトークンを渡さないでください - サーバーはそのようなリクエストを 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.1.0

ユーザーはヘッダー経由で渡された個々のトークンを使用して接続し、ユーザーごとの RBAC 適用が可能になります。

トラブルシューティング

企業プロキシ / TLS インスペクション (Zscaler など)

TLS インスペクションを実行する企業プロキシ (Zscaler Internet Access など) の背後にいる場合、証明書エラーが表示されることがあります:

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.1.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.1.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 で Issue を作成してください。

一般的な質問やディスカッションについては、GitHub Discussion を作成してください。