Terraform MCP Server

Terraform MCP Server

Terraform MCP Server 是一個 Model Context Protocol (MCP) 伺服器，可與 Terraform Registry 和 HCP Terraform API 無縫整合，為 Infrastructure as Code (IaC) 開發提供進階自動化與互動能力。

目錄

功能特色

• 雙傳輸支援：支援 Stdio 與 StreamableHTTP 傳輸，並提供可設定的端點
• Terraform Registry 整合：直接整合公開 Terraform Registry API，支援 providers、modules 與 policies
• HCP Terraform 與 Terraform Enterprise 支援：完整的工作區管理、組織/專案列表與私有 registry 存取
• 工作區操作：建立、更新、刪除工作區，支援變數、標籤與 run 管理
• 用於監控工具使用情況的 OTel 指標：整合 open telemetry meters，在 Streamable HTTP 模式下追蹤工具呼叫量、延遲與失敗。啟用此功能時也會公開預設的 HTTP 伺服器指標

安全性注意事項： 視查詢內容而定，MCP 伺服器可能會向 MCP 用戶端與 LLM 公開某些 Terraform 資料。請勿將 MCP 伺服器與不受信任的 MCP 用戶端或 LLM 搭配使用。

法律注意事項： 您使用第三方 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 編碼代理處理您的專案。一個 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 的 agent mode 文件 中使用 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"
        ]
      }
    }
  }
}

您可以選擇性地將類似的範例（即不含 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.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）或透過 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.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 擴充功能搭配使用

為確保安全，請避免將憑證寫死在程式中，請建立或更新 ~/.gemini/.env（其中 ~ 是您的主目錄或專案目錄）以儲存 HCP Terraform 或 Terraform Enterprise 憑證。

# ~/.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
    }
  }
}

從原始碼安裝

使用最新發行版本：

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_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:

可用指標

系統會收集兩種類型的指標。 首先，透過使用 otelhttp.NewHandler(...) 包裝 HTTP mux，加入標準的 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 傳輸，同時支援直接 HTTP 請求與伺服器傳送事件（SSE）串流。這是遠端/分散式設定的建議傳輸方式。

功能：

• 端點：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 傳輸時支援兩種工作階段模式：

• 有狀態模式（預設）：在請求之間維持工作階段狀態，實現具情境感知的操作。
• 無狀態模式：每個請求獨立處理，不維持工作階段狀態，這對於高可用性部署或使用負載平衡器時很有用。

若要啟用無狀態模式，請設定環境變數：

export MCP_SESSION_MODE=stateless

集中式部署的 Token 傳遞

當集中執行 MCP 伺服器（StreamableHTTP 模式）供多位使用者使用時，每位使用者可以透過 HTTP 標頭傳遞自己的 Terraform token 以進行 RBAC 強制執行。這允許單一伺服器實例服務具有不同權限的多位使用者。

當設定了 MCP_ORGANIZATION_ALLOWLIST 或 --organization-allowlist 時，允許清單必須是 HCP Terraform 組織名稱的 CSV 清單。伺服器要求 Authorization: Bearer <token>，且除非該 token 可以存取 CSV 允許清單中的至少一個組織，否則會拒絕請求。如果請求也包含 TFE_TOKEN 標頭，則 bearer token 優先，確保通過允許清單驗證的 token 就是用於 Terraform API 請求的 token。組織名稱比對不區分大小寫。如果設定的 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 token 重新導向到惡意伺服器。
• 託管部署識別： 設定 TF_MCP_SHARED_SECRET 會將該值作為 X-Tf-Mcp-Secret 標頭傳送到每個 HCP Terraform / TFE 請求，讓後端識別來自已知託管部署的請求（例如套用 IP 允許清單）。這是在標頭中傳送的靜態機密，因此請僅在 TLS 上使用，並將該值視為憑證。
• 絕不要在查詢參數中傳遞 token - 伺服器會以 400 錯誤拒絕此類請求。
• 集中部署時，請務必使用 TLS（MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE）以保護傳輸中的 token。
• 設定 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

使用者接著使用透過標頭傳遞的個人 token 連線，實現每位使用者的 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.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. 複製（Fork）儲存庫
2. 建立您的功能分支
3. 進行您的變更
4. 執行測試
5. 提交拉取請求（Pull Request）

授權

此專案採用 MPL-2.0 開放原始碼授權條款。請參閱 LICENSE 檔案以了解完整條款。

安全性

如有安全性問題，請聯絡 security@hashicorp.com 或遵循我們的安全性政策。

支援

如需回報錯誤或提出功能請求，請在 GitHub 上開啟 issue。

如有一般問題或討論，請開啟 GitHub Discussion。