mcpField
H
HCP Terraform MCP Server

HCP Terraform MCP Server

ローカル
github.com/BBBmauクラウド・インフラ1.6k今日更新

HCP Terraform MCP Server について

HCP Terraform MCP Serverは、MCPクライアントをTerraform Registry、HCP Terraform、Terraform EnterpriseのAPIに接続し、IaCワークフローを支援します。レジストリ検索やワークスペース操作をstdioまたはStreamableHTTPで利用できます。

主な機能

  1. 01プロバイダー、モジュール、ポリシーの検索
  2. 02HCP TerraformとTerraform Enterpriseへのアクセス
  3. 03ワークスペースと実行の管理
  4. 04stdioとStreamableHTTPのトランスポート
  5. 05ツール使用メトリクスの任意設定

活用シーン

  1. 01Terraformプロバイダー、モジュール、ポリシーの検索
  2. 02組織、プロジェクト、プライベートレジストリ項目の確認
  3. 03ワークスペースの作成・更新と実行管理

MCP 対応

Terraform Registry、HCP Terraform、Terraform Enterpriseの操作をMCPクライアントに提供するMCPサーバーです。stdioとStreamableHTTPに対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

README の画像 Terraform MCP サーバー

Terraform MCP サーバーは、Terraform Registry および HCP Terraform API とシームレスに連携する Model Context Protocol(MCP) サーバーです。Infrastructure as Code(IaC)開発の高度な自動化と対話機能を実現します。

目次

はじめにクライアント連携ビルドと実行
機能
前提条件
コマンドラインオプション
手順
インストール
Visual Studio Code
Cursor
Claude Desktop、Amazon Q Developer、Kiro CLI
Claude Code
Codex CLI
Gemini 拡張機能
Bob IDE と Shell
OpenCode
ソースからインストール
Docker イメージをローカルでビルド
トランスポートのサポート
Stdio トランスポート
StreamableHTTP トランスポート
サーバーの機能デプロイとセキュリティヘルプと貢献
利用可能なツール
利用可能なリソース
利用可能なメトリクス
ツールのフィルタリング
セッションモード
一元管理型デプロイでのトークンパススルー
クライアント IP の転送
信頼モデル
信頼するホップ
制限事項
以前のバージョンからの移行
サポートされるヘッダー
セキュリティに関する考慮事項
一元管理型デプロイの例
トラブルシューティング
企業プロキシと TLS インスペクション
開発
貢献
ライセンス
セキュリティ
サポート
## 機能
  • デュアルトランスポート対応:設定可能なエンドポイントを備えた 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 アシスタントをインストールしてください。

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

環境変数:

変数説明デフォルト
TFE_ADDRESSAPI 呼び出しに使用する Terraform Enterprise/HCP Terraform のアドレスを設定します。プロトコルを含める必要があります(例:https://app.terraform.io)。streamable-http モードでは、アドレスを設定する唯一の方法です。クライアントからヘッダーまたはクエリパラメーターで指定することはできません。任意
TFE_TOKENTerraform Enterprise API トークン""(空)
TF_MCP_SHARED_SECRETHCP Terraform / TFE へのリクエストで X-Tf-Mcp-Secret ヘッダーとして送信される共有シークレットです。ホストされた MCP デプロイメントからのリクエストを識別するために使用します。TLS 経由でのみ使用してください。""(空)
TFE_SKIP_TLS_VERIFYHCP Terraform または Terraform Enterprise の TLS 検証をスキップしますfalse
LOG_LEVELログレベル:trace、debug、info、warn、error、fatal、panic(--log-level フラグを上書きします)info
LOG_FORMATログ形式:text または json(--log-format フラグを上書きします)text
TRANSPORT_MODEHTTP トランスポートを有効にするには streamable-http に設定します(従来の http 値も引き続きサポートされます)stdio
TRANSPORT_HOSTHTTP サーバーのバインド先ホスト127.0.0.1
TRANSPORT_PORTHTTP サーバーのポート8080
MCP_ENDPOINTHTTP サーバーのエンドポイントパス/mcp
MCP_REDIRECT_ROOT_URL/ へのリクエストのリダイレクト先 URL""
MCP_KEEP_ALIVESSE 接続のキープアライブ間隔(例:30s、1m)。無効にするには 0 を指定します0
MCP_SESSION_MODEセッションモード:stateful または statelessstateful
MCP_ALLOWED_ORIGINSCORS で許可するオリジンのカンマ区切りリスト""(空)
MCP_CORS_MODECORS モード:strict、development、または disabledstrict
MCP_TLS_CERT_FILETLS 証明書ファイルへのパス。localhost 以外へのデプロイで必要です(例:/path/to/cert.pem)""(空)
MCP_TLS_KEY_FILETLS キーファイルへのパス。localhost 以外へのデプロイで必要です(例:/path/to/key.pem)""(空)
MCP_RATE_LIMIT_GLOBALグローバルレート制限(形式:rps:burst)10:20
MCP_RATE_LIMIT_SESSIONセッションごとのレート制限(形式:rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTHTTP サーバーへのアクセスを許可する HCP Terraform 組織名の CSV リスト""(空)
MCP_FORWARD_CLIENT_IPX-Forwarded-For を使用してクライアント IP を HCP Terraform / TFE に転送します。有効にするには true に設定しますfalse
MCP_REMOTE_IP_METHOD転送が有効な場合のクライアント IP の取得方法:RemoteAddr(直接接続のみ)、X-Real-IP、または X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSX-Forwarded-For チェーンの右側から数えた、信頼するプロキシホップ数です。MCP_REMOTE_IP_METHOD=X-Forwarded-For の場合にのみ使用されます0
ENABLE_TF_OPERATIONS明示的な承認を必要とするツールを有効にしますfalse
OTEL_METRICS_ENABLEDotel を使用してツールとサーバーのメトリクスを有効にしますfalse
OTEL_METRICS_SERVICE_VERSIONメトリクスを送信する terraform-mcp-server のバージョンです。メトリクス属性の設定に使用されます。また、異なるデプロイメント間でメトリクスを追跡するのにも役立ちますlatest
OTEL_METRICS_SERVICE_NAMEメトリクスの送信元を識別します(例:"terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALメトリクスのフラッシュ頻度を制御します2
OTEL_METRICS_ENDPOINTOTel Collector またはバックエンドの URLlocalhost:4318
INSTANA_ENABLEDstreamable-http サーバーの Instana インストルメンテーション(メトリクスと HTTP リクエストのトレース)を有効にします。サーバーから到達可能な Instana エージェントが必要です。false
INSTANA_SERVICE_NAMEInstana インストルメンテーションが有効な場合に、MCP サーバーに使用するサービス名terraform-mcp-server
# 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 での使用

以下の JSON ブロックを、VS Code のユーザー設定(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.4.1"
        ]
      }
    },
    "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": {
        "type": "http",
        "url": "https://mcp.terraform.io/mcp",
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

任意で、同様の例(つまり、mcp キーなし)をワークスペース内の .vscode/mcp.json というファイルに追加できます。これにより、設定を他のユーザーと共有できます。

ローカルリモート
{
  "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.4.1"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}
{
  "servers": {
    "terraform": {
      "type": "http",
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

VS Code にインストール(docker) VS Code Insiders にインストール(docker)

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.4.1"
      ]
    }
  }
}
{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}
terraform MCP サーバーを Cursor に追加
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.4.1"
      ]
    }
  }
}
{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

NOTE: Claude Desktop は設定ファイルによるリモート MCP サーバーの設定をサポートしていません。代わりにカスタムコネクタを使用してください。

Claude Code での使用

Claude Code で MCP サーバーのツールを使用および追加する方法については、ユーザードキュメントをご覧ください。

ローカルリモート
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
claude mcp add terraform -s user -t http \
  --header "Authorization: Bearer <<TFE_TOKEN>>" \
  https://mcp.terraform.io/mcp
### Codex CLI での使用方法

Codex CLI で MCP サーバーツールを使用、追加する方法については、ユーザードキュメントをご覧ください。

注: 認証が必要な HCP Terraform または Terraform Enterprise のツールでは、Docker コマンドに TFE_ADDRESS と TFE_TOKEN を追加してください。

ローカルリモート
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

codex mcp add にはカスタムヘッダーを指定するフラグがないため、サーバーを ~/.codex/config.toml に追加してください。

[mcp_servers.terraform]
url = "https://mcp.terraform.io/mcp"
http_headers = { "Authorization" = "Bearer <<TFE_TOKEN>>" }
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.4.1"
      ],
      "disabled": false
    }
  }
}
{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      },
      "disabled": false
    }
  }
}
OpenCode での使用方法

OpenCode で MCP サーバーを使用、追加する方法については、ユーザードキュメントをご覧ください。サーバーをプロジェクトの opencode.json またはグローバル設定の ~/.config/opencode/opencode.json に追加してください。

ローカルリモート
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "terraform": {
        "type": "local",
        "command": [
          "docker",
          "run",
          "-i",
          "--rm",
          "-e", "TFE_ADDRESS",
          "-e", "TFE_TOKEN",
          "hashicorp/terraform-mcp-server:1.4.1"
        ],
        "environment": {
          "TFE_ADDRESS": "{env:TFE_ADDRESS}",
          "TFE_TOKEN": "{env:TFE_TOKEN}"
        }
      }
    }
  }
}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "terraform": {
        "type": "remote",
        "url": "https://mcp.terraform.io/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}
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": "http",
        "url": "https://mcp.terraform.io/mcp",
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

Docker イメージをローカルでビルドする

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

  1. リポジトリをクローンします。
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Docker イメージをビルドします。
make docker-build
  1. これにより、次の設定で使用できるローカル 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 を設定してください。

  1. (任意)http モードで接続をテストします。
# Test the connection
curl http://localhost:8080/health
  1. 次のように AI アシスタントで使用できます。
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

利用可能なツール

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

利用可能なリソース

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

利用可能なメトリクス

2 種類のメトリクスが収集されます。 1 つ目は、HTTP mux を otelhttp.NewHandler(...) でラップして追加される標準の HTTP サーバーメトリクスです。次のメトリクスが出力されます。

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

2 つ目は、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 ヘッダーも含まれている場合は、Bearer トークンが優先されます。これにより、許可リストによる検証に使用したトークンが Terraform API リクエストにも使用されます。組織名の照合では、大文字と小文字は区別されません。設定された CSV 値を解析して組織名が 1 つも得られない場合、サーバーは組織の許可リストの形式が不正であることを示すエラーを出して終了します。

クライアント IP の転送

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

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

方法動作
RemoteAddr(デフォルト)直接の TCP 接続元のアドレスのみを使用します。X-Forwarded-For と X-Real-IP は無視します。
X-Real-IPX-Real-IP ヘッダーが有効な IP の場合はその値を使用し、それ以外の場合は RemoteAddr にフォールバックします。
X-Forwarded-ForX-Forwarded-For ヘッダーを使用し、右から MCP_XFF_TRUSTED_HOPS 番目の値を選択します。値がないか無効な場合は RemoteAddr にフォールバックします。
信頼モデル

X-Forwarded-For と X-Real-IP はクライアントと中継プロキシによって設定されるため、サーバーの前段にある信頼できるプロキシがこれらの値を上書きしない限り、偽装される可能性があります。このため、デフォルトは RemoteAddr となっており、サーバーが直接接続している相手のみを信頼します。X-Real-IP または X-Forwarded-For を有効にするのは、これらのヘッダーを設定する、自分が管理するプロキシの背後にサーバーがある場合に限ってください。AWS Application Load Balancers を含む一部のロードバランサーは X-Real-IP を設定しません。その場合、このヘッダーはクライアントから直接渡されるため、使用すべきではありません。

信頼するホップ数

X-Forwarded-For を使用する場合、サーバーの前段で運用しているプロキシの数を MCP_XFF_TRUSTED_HOPS に設定してください。各プロキシは自身のアドレスではなく、リクエストを受信した送信元のアドレスを追加するため、右から指定した位置にある値がクライアント IP です。それより左にある値はクライアントが送信したものであり、偽装される可能性があります。

たとえば、AWS ALB のようなロードバランサーが 1 つある場合は、MCP_XFF_TRUSTED_HOPS=1 を設定します。198.51.100.7 というヘッダーは 198.51.100.7 として解決されます。また、クライアントが 1.2.3.4 自体を送信した 1.2.3.4, 198.51.100.7 というヘッダーも、198.51.100.7 として解決されます。MCP_XFF_TRUSTED_HOPS=2 で 1.2.3.4, 198.51.100.7, 10.0.0.5 の場合、サーバーは 198.51.100.7 を選択します。ホップ数がエントリー数を超える場合、または選択されたエントリーが有効な IP でない場合、サーバーは RemoteAddr にフォールバックします。

ホップ数を大きく設定しすぎると、クライアントが指定した値を信頼してしまいます。小さく設定しすぎると、自社インフラ内のアドレスが選択されます。運用しているプロキシの数と正確に一致する値を設定してください。

制限事項
  • リクエストに複数の X-Forwarded-For ヘッダーが含まれる場合、サーバーはエントリーを選択する前に、それらを順番に連結します。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 に設定してください。

サポートされるヘッダー
ヘッダー説明
TFE_TOKENTerraform API トークン
Authorization: Bearer <token>標準の Bearer 認証を使用する代替方法
TFE_SKIP_TLS_VERIFYリクエストの TLS 検証をスキップします
例: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.4.1

その後、ユーザーは各自のトークンをヘッダー経由で渡して接続するため、ユーザーごとの 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.4.1

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.4.1"
      ]
    }
  }
}

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

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

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

開発

前提条件
  • Go(特定のバージョンについては go.mod ファイルを確認してください)
  • Docker(任意。コンテナのビルドに使用)
利用可能な Make コマンド
コマンド説明
make buildバイナリをビルドします
make testすべてのテストを実行します
make test-e2eエンドツーエンドテストを実行します
make docker-buildDocker イメージをビルドします
make run-httpHTTP サーバーをローカルで実行します
make docker-run-httpDocker で HTTP サーバーを実行します
make test-httpHTTP ヘルスエンドポイントをテストします
make cleanビルド成果物を削除します
make help利用可能なすべてのコマンドを表示します

コントリビューション

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

ライセンス

このプロジェクトは、オープンソースライセンスである MPL-2.0 の条件に基づいてライセンスされています。ライセンスの全文については、LICENSE ファイルをご確認ください。

セキュリティ

セキュリティに関する問題は、[email protected] までご連絡いただくか、セキュリティポリシーに従ってください。

サポート

バグの報告や機能のリクエストは、GitHub で Issue を作成してください。

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

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。