Terraform MCP Server

Terraform MCP 伺服器

Terraform MCP 伺服器是一個模型上下文協定 (MCP) 伺服器，提供與 Terraform Registry API 的無縫整合，為基礎架構即程式碼 (IaC) 開發實現進階的自動化和互動功能。

功能特色

• 雙重傳輸支援：同時支援 Stdio 和 StreamableHTTP 傳輸，並提供可設定的端點
• Terraform Registry 整合：直接整合公開的 Terraform Registry API，用於提供者、模組和政策
• HCP Terraform 和 Terraform Enterprise 支援：完整的工作區管理、組織/專案清單以及私有 Registry 存取
• 工作區操作：建立、更新、刪除工作區，並支援變數、標籤和執行管理
• 用於監控工具使用情況的 OTel 指標：整合 OpenTelemetry 儀表，以在 Streamable HTTP 模式下追蹤工具呼叫量、延遲和失敗。啟用此功能時，也會公開預設的 HTTP 伺服器指標

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

法律注意事項： 您使用第三方 MCP 用戶端/LLM 的行為，完全受該 MCP/LLM 的使用條款約束，IBM 不對此類第三方工具的效能負責。IBM 明確否認對第三方 MCP 用戶端/LLM 的任何及所有保證和責任，且可能無法提供支援來解決由第三方工具引起的問題。

注意事項： MCP 伺服器提供的輸出和建議是動態產生的，可能會因查詢、模型和所連接的 MCP 用戶端而異。使用者在實作前，應徹底審查所有輸出/建議，以確保其符合組織的安全最佳實務、成本效益目標和合規要求。

先決條件

1. 確保已安裝並執行 Docker，以便在容器化環境中使用伺服器。
2. 安裝支援模型上下文協定 (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，若要使用它，請將名為 AGENTS.md 的檔案提交到您的 Terraform 設定所在的目錄。

安裝

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

或者，您可以將類似的範例 (即不含 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.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) 或透過「設定」→「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.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 擴充功能搭配使用

為了安全起見，請避免在程式碼中硬編碼您的憑證，建立或更新 ~/.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 中使用 MCP 中，進一步了解如何在 Bob IDE 或 Shell 中使用和新增 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"
      ],
      "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

集中式部署的權杖傳遞

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

當設定了 MCP_ORGANIZATION_ALLOWLIST 或 --organization-allowlist 時，允許清單必須是 HCP Terraform 組織名稱的 CSV 清單。伺服器需要 Authorization: Bearer <token>，並且會拒絕請求，除非該權杖可以存取 CSV 允許清單中的至少一個組織。如果請求也包含 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. Fork 此儲存庫
2. 建立您的功能分支
3. 進行您的變更
4. 執行測試
5. 提交 Pull Request

授權

本專案依據 MPL-2.0 開放原始碼授權條款授權。請參閱 LICENSE 檔案以取得完整條款。

安全性

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

支援

如需錯誤回報和功能請求，請在 GitHub 上開啟 Issue。

如需一般問題和討論，請開啟 GitHub Discussion。