Terraform MCP Server

chính thức

Máy chủ MCP HashiCorp Terraform cho quy trình làm việc Cơ sở hạ tầng dưới dạng Mã, bao gồm khám phá nhà cung cấp và mô-đun thông qua Terraform Registry.

Bạn có thể làm gì với Terraform MCP?

  • Tìm kiếm Terraform Registry — Yêu cầu tìm nhà cung cấp hoặc mô-đun bằng cách sử dụng search_providersget_provider_details từ registry công khai.
  • Quản lý không gian làm việc HCP Terraform — Tạo, cập nhật hoặc xóa không gian làm việc và xử lý biến, thẻ, cũng như các lần chạy thông qua các thao tác không gian làm việc.
  • Liệt kê tổ chức và dự án — Truy xuất danh sách tổ chức và dự án từ HCP Terraform hoặc Terraform Enterprise.
  • Truy cập nội dung registry riêng tư — Truy vấn nhà cung cấp, mô-đun và chính sách của registry riêng tư bằng bộ công cụ registry-private.
  • Lọc các công cụ khả dụng — Chỉ bật các khả năng cần thiết bằng cách sử dụng cờ --toolsets hoặc --tools như list_workspaces.

Tài liệu

Terraform MCP Server

Terraform MCP Server là một máy chủ Model Context Protocol (MCP) tích hợp liền mạch với các API của Terraform RegistryHCP Terraform, cho phép tự động hóa và tương tác nâng cao cho việc phát triển Infrastructure as Code (IaC).

Mục lục

Bắt đầuTích hợp máy kháchXây dựng và chạy
Tính năng
Điều kiện tiên quyết
Tùy chọn dòng lệnh
Hướng dẫn
Cài đặt
Visual Studio Code
Cursor
Claude Desktop, Amazon Q Developer, và Kiro CLI
Claude Code
Codex CLI
Tiện ích mở rộng Gemini
Bob IDE và Shell
Cài đặt từ mã nguồn
Xây dựng Docker Image cục bộ
Hỗ trợ truyền tải
Truyền tải Stdio
Truyền tải StreamableHTTP
Khả năng của máy chủTriển khai và bảo mậtTrợ giúp và đóng góp
Công cụ khả dụng
Tài nguyên khả dụng
Chỉ số khả dụng
Lọc công cụ
Chế độ phiên
Chuyển tiếp token cho triển khai tập trung
Chuyển tiếp IP máy khách
Mô hình tin cậy
Bước nhảy tin cậy
Giới hạn
Di chuyển từ các phiên bản trước
Tiêu đề được hỗ trợ
Cân nhắc bảo mật
Ví dụ triển khai tập trung
Xử lý sự cố
Proxy doanh nghiệp và kiểm tra TLS
Phát triển
Đóng góp
Giấy phép
Bảo mật
Hỗ trợ

Tính năng

  • Hỗ trợ truyền tải kép: Cả hai truyền tải Stdio và StreamableHTTP với các điểm cuối có thể cấu hình
  • Tích hợp Terraform Registry: Tích hợp trực tiếp với các API Terraform Registry công khai cho providers, modules, và policies
  • Hỗ trợ HCP Terraform & Terraform Enterprise: Quản lý workspace đầy đủ, liệt kê tổ chức/dự án, và truy cập private registry
  • Thao tác Workspace: Tạo, cập nhật, xóa workspace với hỗ trợ biến, thẻ, và quản lý run
  • Chỉ số OTel để giám sát việc sử dụng công cụ: Tích hợp với open telemetry meters để theo dõi khối lượng gọi công cụ, độ trễ và lỗi trong chế độ Streamable HTTP. Cũng hiển thị các chỉ số máy chủ http mặc định khi tính năng này được bật

Lưu ý bảo mật: Tùy thuộc vào truy vấn, máy chủ MCP có thể hiển thị một số dữ liệu Terraform nhất định cho máy khách MCP và LLM. Không sử dụng máy chủ MCP với các máy khách MCP hoặc LLM không đáng tin cậy.

Lưu ý pháp lý: Việc bạn sử dụng MCP Client/LLM của bên thứ ba chỉ tuân theo các điều khoản sử dụng của MCP/LLM đó, và IBM không chịu trách nhiệm về hiệu suất của các công cụ bên thứ ba đó. IBM từ chối rõ ràng mọi bảo hành và trách nhiệm pháp lý đối với MCP Clients/LLMs của bên thứ ba, và có thể không cung cấp hỗ trợ để giải quyết các sự cố do các công cụ bên thứ ba gây ra.

Thận trọng: Các đầu ra và khuyến nghị do máy chủ MCP cung cấp được tạo động và có thể thay đổi tùy theo truy vấn, mô hình và máy khách MCP được kết nối. Người dùng nên xem xét kỹ lưỡng tất cả các đầu ra/khuyến nghị để đảm bảo chúng phù hợp với các phương pháp bảo mật tốt nhất, mục tiêu hiệu quả chi phí và yêu cầu tuân thủ của tổ chức trước khi triển khai.

Điều kiện tiên quyết

  1. Đảm bảo Docker được cài đặt và đang chạy để sử dụng máy chủ trong môi trường containerized.
  2. Cài đặt một trợ lý AI hỗ trợ Model Context Protocol (MCP).

Tùy chọn dòng lệnh

Biến môi trường:

BiếnMô tảMặc định
TFE_ADDRESSĐặt địa chỉ Terraform Enterprise/HCP Terraform cho các lệnh gọi API. Phải bao gồm giao thức (ví dụ: https://app.terraform.io). Trong chế độ streamable-http, đây là cách duy nhất để đặt địa chỉ; không thể được cung cấp bởi máy khách qua header hoặc tham số truy vấn.Tùy chọn
TFE_TOKENToken API Terraform Enterprise"" (trống)
TF_MCP_SHARED_SECRETBí mật dùng chung được gửi dưới dạng header X-Tf-Mcp-Secret trên các yêu cầu đến HCP Terraform / TFE, dùng để xác định các yêu cầu xuất phát từ triển khai MCP được lưu trữ. Chỉ nên sử dụng qua TLS."" (trống)
TFE_SKIP_TLS_VERIFYBỏ qua xác minh TLS của HCP Terraform hoặc Terraform Enterprisefalse
LOG_LEVELMức ghi log: trace, debug, info, warn, error, fatal, panic (ghi đè cờ --log-level)info
LOG_FORMATĐịnh dạng ghi log: text hoặc json (ghi đè cờ --log-format)text
TRANSPORT_MODEĐặt thành streamable-http để bật truyền tải HTTP (giá trị http cũ vẫn được hỗ trợ)stdio
TRANSPORT_HOSTMáy chủ để liên kết máy chủ HTTP127.0.0.1
TRANSPORT_PORTCổng máy chủ HTTP8080
MCP_ENDPOINTĐường dẫn điểm cuối máy chủ HTTP/mcp
MCP_REDIRECT_ROOT_URLURL để chuyển hướng các yêu cầu đến /""
MCP_KEEP_ALIVEKhoảng thời gian keep-alive cho các kết nối SSE (ví dụ: 30s, 1m). 0 để tắt0
MCP_SESSION_MODEChế độ phiên: stateful hoặc statelessstateful
MCP_ALLOWED_ORIGINSDanh sách phân tách bằng dấu phẩy các nguồn gốc được phép cho CORS"" (trống)
MCP_CORS_MODEChế độ CORS: strict, development, hoặc disabledstrict
MCP_TLS_CERT_FILEĐường dẫn đến tệp chứng chỉ TLS, bắt buộc cho triển khai không phải localhost (ví dụ: /path/to/cert.pem)"" (trống)
MCP_TLS_KEY_FILEĐường dẫn đến tệp khóa TLS, bắt buộc cho triển khai không phải localhost (ví dụ: /path/to/key.pem)"" (trống)
MCP_RATE_LIMIT_GLOBALGiới hạn tốc độ toàn cầu (định dạng: rps:burst)10:20
MCP_RATE_LIMIT_SESSIONGiới hạn tốc độ mỗi phiên (định dạng: rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTDanh sách CSV các tên tổ chức HCP Terraform được phép truy cập máy chủ HTTP"" (trống)
MCP_FORWARD_CLIENT_IPChuyển tiếp IP máy khách đến HCP Terraform / TFE qua X-Forwarded-For. Đặt thành true để bậtfalse
MCP_REMOTE_IP_METHODCách IP máy khách được lấy nguồn khi bật chuyển tiếp: RemoteAddr (chỉ kết nối trực tiếp), X-Real-IP, hoặc X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSSố bước nhảy proxy tin cậy được đếm từ bên phải của chuỗi X-Forwarded-For. Chỉ được sử dụng khi MCP_REMOTE_IP_METHOD=X-Forwarded-For0
ENABLE_TF_OPERATIONSBật các công cụ yêu cầu phê duyệt rõ ràngfalse
OTEL_METRICS_ENABLEDBật các công cụ và chỉ số máy chủ sử dụng otelfalse
OTEL_METRICS_SERVICE_VERSIONPhiên bản của terraform-mcp-server gửi chỉ số, được sử dụng để đặt các thuộc tính chỉ số. Cũng giúp theo dõi chỉ số trên các triển khai khác nhaulatest
OTEL_METRICS_SERVICE_NAMEXác định nguồn của chỉ số (ví dụ: "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALKiểm soát tần suất xả chỉ số2
OTEL_METRICS_ENDPOINTURL của OTel Collector hoặc backend của bạnlocalhost:4318
INSTANA_ENABLEDBật công cụ Instana instrumentation (chỉ số và theo dõi yêu cầu HTTP) cho máy chủ streamable-http. Yêu cầu một agent Instana mà máy chủ có thể truy cập.false
INSTANA_SERVICE_NAMENếu bật công cụ Instana instrumentation, tên dịch vụ để sử dụng cho máy chủ MCPterraform-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>]

Hướng dẫn

Hướng dẫn mặc định cho máy chủ MCP nằm tại cmd/terraform-mcp-server/instructions.md, nếu chúng không phù hợp với các phương pháp Terraform của tổ chức bạn hoặc nếu máy chủ MCP tạo ra phản hồi không chính xác, vui lòng thay thế chúng bằng hướng dẫn của riêng bạn và xây dựng lại container hoặc binary. Một ví dụ về hướng dẫn như vậy nằm tại instructions/example-mcp-instructions.md

AGENTS.md về cơ bản hoạt động như README cho các agent mã hóa: một nơi chuyên dụng, có thể dự đoán để cung cấp ngữ cảnh và hướng dẫn giúp các agent mã hóa AI làm việc trên dự án của bạn. Một tệp AGENTS.md hoạt động với các agent mã hóa khác nhau. Một ví dụ về hướng dẫn như vậy nằm tại instructions/example-AGENTS.md, để sử dụng nó, hãy commit một tệp có tên AGENTS.md vào thư mục nơi chứa các cấu hình Terraform của bạn.

Cài đặt

Sử dụng với Visual Studio Code

Thêm khối JSON sau vào tệp User Settings (JSON) của bạn trong VS Code. Bạn có thể thực hiện điều này bằng cách nhấn Ctrl + Shift + P và gõ Preferences: Open User Settings (JSON).

Tìm hiểu thêm về việc sử dụng các công cụ máy chủ MCP trong tài liệu chế độ agent của VS Code.

Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc thấp hơn
{
  "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"
        ]
      }
    }
  }
}

Tùy chọn, bạn có thể thêm một ví dụ tương tự (tức là không có khóa mcp) vào một tệp có tên .vscode/mcp.json trong workspace của bạn. Điều này sẽ cho phép bạn chia sẻ cấu hình với người khác.

Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc thấp hơn
{
  "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"
      ]
    }
  }
}

Install in VS Code (docker) Install in VS Code Insiders (docker)

Sử dụng với Cursor

Thêm phần này vào cấu hình Cursor của bạn (~/.cursor/mcp.json) hoặc qua Settings → Cursor Settings → MCP:

Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc thấp hơn
{
  "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"
      ]
    }
  }
}
Add terraform MCP server to Cursor

Sử dụng với Claude Desktop / Amazon Q Developer / Kiro CLI

Tìm hiểu thêm về cách sử dụng các công cụ MCP server trong Claude Desktop tài liệu người dùng. Đọc thêm về cách sử dụng MCP server trong Amazon Q DeveloperKiro CLI.

Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc cũ hơn
{
  "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"
      ]
    }
  }
}

Sử dụng với Claude Code

Tìm hiểu thêm về cách sử dụng và thêm các công cụ MCP server trong Claude Code tài liệu người dùng

  • Transport cục bộ (stdio)
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Transport từ xa (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

Sử dụng với Codex CLI

Tìm hiểu thêm về cách sử dụng và thêm các công cụ MCP server trong Codex CLI tài liệu người dùng.

Lưu ý: Thêm TFE_ADDRESSTFE_TOKEN vào các lệnh Docker cho các công cụ HCP Terraform hoặc Terraform Enterprise đã xác thực.

  • Transport cục bộ (stdio)
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server
  • Transport từ xa (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

Sử dụng với tiện ích mở rộng Gemini

Vì lý do bảo mật, tránh mã hóa cứng thông tin xác thực của bạn, hãy tạo hoặc cập nhật ~/.gemini/.env (trong đó ~ là thư mục chính hoặc thư mục dự án của bạn) để lưu trữ thông tin xác thực HCP Terraform hoặc Terraform Enterprise

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

Cài đặt tiện ích mở rộng và chạy Gemini

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

Sử dụng với Bob IDE / Shell

Tìm hiểu thêm về cách sử dụng và thêm các công cụ MCP server trong Bob IDE hoặc Shell Sử dụng MCP trong Bob.

Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc cũ hơn
{
  "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
    }
  }
}

Cài đặt từ mã nguồn

Sử dụng phiên bản phát hành mới nhất:

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

Sử dụng nhánh chính:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Phiên bản 0.3.0+ hoặc mới hơnPhiên bản 0.2.3 hoặc cũ hơn
{
  "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"
      }
    }
  }
}

Xây dựng Docker Image cục bộ

Trước khi sử dụng server, bạn cần xây dựng Docker image cục bộ:

  1. Sao chép kho lưu trữ:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Xây dựng Docker image:
make docker-build
  1. Thao tác này sẽ tạo một Docker image cục bộ mà bạn có thể sử dụng trong cấu hình sau.
# 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

Lưu ý: Khi chạy trong Docker, bạn nên đặt TRANSPORT_HOST=0.0.0.0 để cho phép kết nối từ bên ngoài container.

  1. (Tùy chọn) Kiểm tra kết nối ở chế độ http
# Test the connection
curl http://localhost:8080/health
  1. Bạn có thể sử dụng nó trên trợ lý AI của mình như sau:
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Các công cụ có sẵn

Xem các công cụ có sẵn tại đây :link:

Các tài nguyên có sẵn

Xem các tài nguyên có sẵn tại đây :link:

Các chỉ số có sẵn

Hai loại chỉ số được thu thập. Đầu tiên, các chỉ số HTTP server tiêu chuẩn được thêm vào bằng cách bọc HTTP mux với otelhttp.NewHandler(...). Điều này phát ra:

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

Thứ hai, MCP server ghi lại các chỉ số công cụ tùy chỉnh xung quanh quá trình thực thi công cụ bằng cách sử dụng các hook MCP (BeforeCallTool / AfterCallTool). Các chỉ số này phát ra:

  1. mcp_tool_calls_total
  2. mcp_tool_errors_total
  3. mcp_tool_duration_seconds

Lọc công cụ

Kiểm soát các công cụ có sẵn bằng cách sử dụng --toolsets (nhóm) hoặc --tools (từng công cụ):

# 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

Các bộ công cụ có sẵn: registry, registry-private, terraform, all, default. Xem pkg/toolsets/mapping.go để biết tên từng công cụ. Không thể sử dụng cả hai cờ cùng lúc.

Hỗ trợ Transport

Terraform MCP Server hỗ trợ nhiều giao thức transport:

1. Stdio Transport (Mặc định)

Giao tiếp đầu vào/đầu ra tiêu chuẩn bằng cách sử dụng thông điệp JSON-RPC. Lý tưởng cho phát triển cục bộ và tích hợp trực tiếp với các MCP client.

2. StreamableHTTP Transport

Transport dựa trên HTTP hiện đại hỗ trợ cả yêu cầu HTTP trực tiếp và luồng Server-Sent Events (SSE). Đây là transport được khuyến nghị cho các thiết lập từ xa/phân tán.

Tính năng:

  • Endpoint: http://{hostname}:8080/mcp
  • Kiểm tra sức khỏe: http://{hostname}:8080/health
  • Cấu hình môi trường: Đặt TRANSPORT_MODE=http hoặc TRANSPORT_PORT=8080 để kích hoạt
  • Danh sách cho phép tổ chức: Đặt MCP_ORGANIZATION_ALLOWLIST hoặc --organization-allowlist thành danh sách CSV các tên tổ chức HCP Terraform được phép

Chế độ phiên

Terraform MCP Server hỗ trợ hai chế độ phiên khi sử dụng transport StreamableHTTP:

  • Chế độ có trạng thái (Mặc định): Duy trì trạng thái phiên giữa các yêu cầu, cho phép các hoạt động nhận biết ngữ cảnh.
  • Chế độ không trạng thái: Mỗi yêu cầu được xử lý độc lập mà không duy trì trạng thái phiên, hữu ích cho các triển khai có tính khả dụng cao hoặc khi sử dụng bộ cân bằng tải.

Để kích hoạt chế độ không trạng thái, đặt biến môi trường:

export MCP_SESSION_MODE=stateless

Chuyển tiếp Token cho các Triển khai Tập trung

Khi chạy MCP server tập trung (chế độ StreamableHTTP) cho nhiều người dùng, mỗi người dùng có thể truyền token Terraform của riêng họ qua các tiêu đề HTTP để thực thi RBAC. Điều này cho phép một phiên bản server duy nhất phục vụ nhiều người dùng với các quyền khác nhau.

Khi MCP_ORGANIZATION_ALLOWLIST hoặc --organization-allowlist được cấu hình, danh sách cho phép phải là danh sách CSV các tên tổ chức HCP Terraform. Server yêu cầu Authorization: Bearer <token> và từ chối các yêu cầu trừ khi token đó có thể truy cập ít nhất một tổ chức trong danh sách cho phép CSV. Token bearer được ưu tiên nếu yêu cầu cũng bao gồm tiêu đề TFE_TOKEN, đảm bảo token được xác thực bởi danh sách cho phép là token được sử dụng cho các yêu cầu API Terraform. Việc khớp tên tổ chức không phân biệt chữ hoa chữ thường. Nếu giá trị CSV được cấu hình phân tích thành không có tên tổ chức nào, server sẽ thoát với lỗi danh sách cho phép tổ chức không hợp lệ.

Chuyển tiếp IP Client

Khi chạy MCP server tập trung phía sau proxy hoặc bộ cân bằng tải, bạn có thể chuyển tiếp IP của client gốc đến HCP Terraform / TFE qua tiêu đề X-Forwarded-For. Tính năng này tắt theo mặc định và phải được kích hoạt bằng MCP_FORWARD_CLIENT_IP=true.

Khi được kích hoạt, server lấy IP client theo MCP_REMOTE_IP_METHOD:

Phương thứcHành vi
RemoteAddr (mặc định)Chỉ sử dụng địa chỉ của kết nối TCP trực tiếp. Bỏ qua X-Forwarded-ForX-Real-IP.
X-Real-IPSử dụng tiêu đề X-Real-IP nếu đó là IP hợp lệ, nếu không sẽ dự phòng sang RemoteAddr.
X-Forwarded-ForSử dụng chuỗi X-Forwarded-For, chọn mục nhập MCP_XFF_TRUSTED_HOPS vị trí từ bên phải. Dự phòng sang RemoteAddr nếu giá trị bị thiếu hoặc không hợp lệ.

Mô hình tin cậy

X-Forwarded-ForX-Real-IP được đặt bởi client và proxy trung gian, vì vậy chúng có thể bị giả mạo trừ khi một proxy đáng tin cậy phía trước server ghi đè chúng. Vì lý do này, mặc định là RemoteAddr, chỉ tin tưởng đối tác mà server được kết nối trực tiếp. Chỉ kích hoạt X-Real-IP hoặc X-Forwarded-For khi server nằm phía sau proxy mà bạn kiểm soát và proxy đó đặt các tiêu đề này.

Số bước nhảy đáng tin cậy

Khi sử dụng X-Forwarded-For, MCP_XFF_TRUSTED_HOPS là số proxy bạn vận hành giữa server và internet. Các bước nhảy được đếm từ bên phải của chuỗi, vì mỗi proxy nối thêm địa chỉ mà nó nhận được yêu cầu và mục nhập ngoài cùng bên phải được đặt bởi proxy gần server nhất. Server bỏ qua số mục nhập đáng tin cậy đó và lấy mục tiếp theo ở bên trái.

Ví dụ: với MCP_XFF_TRUSTED_HOPS=1 và tiêu đề 200.1.2.3, 10.1.1.10, server chọn 200.1.2.3. Với MCP_XFF_TRUSTED_HOPS=2108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1, nó chọn 200.1.2.3. Nếu số bước nhảy lớn hơn số mục nhập hoặc mục nhập được chọn không phải là IP hợp lệ, server sẽ dự phòng sang RemoteAddr.

Đặt số bước nhảy quá thấp sẽ tin tưởng giá trị do client cung cấp; đặt quá cao sẽ tin tưởng một địa chỉ sâu hơn trong cơ sở hạ tầng của chính bạn. Đặt nó chính xác bằng số proxy bạn vận hành.

Hạn chế

  • Server chỉ đọc tiêu đề X-Forwarded-For đầu tiên trên một yêu cầu. Một yêu cầu có thể mang nhiều tiêu đề X-Forwarded-For là hợp lệ, nhưng thư viện chuẩn của Go chỉ trả về tiêu đề đầu tiên và server không nối chúng lại. Nếu chuỗi proxy của bạn phát ra nhiều tiêu đề, hãy cấu hình nó để phát ra một tiêu đề X-Forwarded-For kết hợp duy nhất.
  • Cả địa chỉ IPv4 và IPv6 đều được hỗ trợ. Các giá trị không phải IP hợp lệ sẽ bị từ chối và server dự phòng sang RemoteAddr.

Di chuyển từ các phiên bản trước

Các phiên bản trước sử dụng giá trị X-Forwarded-For ngoài cùng bên trái khi tiêu đề có mặt, không có cấu hình. Điều này không an toàn vì giá trị ngoài cùng bên trái dễ bị giả mạo nhất. Mặc định hiện tại là RemoteAddr. Nếu bạn chạy server phía sau proxy và dựa vào X-Forwarded-For được chuyển tiếp đến HCP Terraform / TFE, hãy đặt MCP_REMOTE_IP_METHOD=X-Forwarded-ForMCP_XFF_TRUSTED_HOPS bằng số proxy bạn vận hành.

Các tiêu đề được hỗ trợ

Tiêu đềMô tả
TFE_TOKENToken API Terraform
Authorization: Bearer <token>Phương thức thay thế sử dụng xác thực Bearer tiêu chuẩn
TFE_SKIP_TLS_VERIFYBỏ qua xác minh TLS cho yêu cầu

Ví dụ: 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",...}'

Cân nhắc bảo mật

  • TFE_ADDRESS không thể được đặt bởi client. Trong chế độ streamable-http, địa chỉ Terraform chỉ được lấy từ biến môi trường TFE_ADDRESS phía server (hoặc mặc định). Các yêu cầu cố gắng đặt TFE_ADDRESS qua tiêu đề HTTP hoặc tham số truy vấn sẽ bị từ chối với mã 403. Điều này ngăn client chuyển hướng các yêu cầu và token Authorization đến một server độc hại.
  • Nhận dạng triển khai được lưu trữ: việc đặt TF_MCP_SHARED_SECRET sẽ gửi giá trị đó làm tiêu đề X-Tf-Mcp-Secret trên mọi yêu cầu HCP Terraform / TFE, cho phép backend nhận dạng các yêu cầu từ một triển khai được lưu trữ đã biết (ví dụ: để áp dụng danh sách cho phép IP). Đây là một bí mật tĩnh được gửi trong tiêu đề, vì vậy chỉ sử dụng nó qua TLS và coi giá trị đó như một thông tin xác thực.
  • Không bao giờ truyền token trong tham số truy vấn - server sẽ từ chối các yêu cầu như vậy với lỗi 400.
  • Luôn sử dụng TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) khi triển khai tập trung để bảo vệ token trong quá trình truyền.
  • Cấu hình MCP_ALLOWED_ORIGINS để hạn chế client nào có thể kết nối.

Ví dụ triển khai tập trung

# 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

Người dùng sau đó kết nối với token cá nhân của họ được truyền qua các tiêu đề, cho phép thực thi RBAC theo từng người dùng.

Xử lý sự cố

Proxy doanh nghiệp / Kiểm tra TLS (Zscaler, v.v.)

Nếu bạn đứng sau proxy doanh nghiệp thực hiện kiểm tra TLS (như Zscaler Internet Access), bạn có thể gặp lỗi chứng chỉ:

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

Giải pháp: Gắn chứng chỉ CA của công ty bạn vào container:

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

Đối với cấu hình MCP client:

{
  "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"
      ]
    }
  }
}

Thay thế: Chạy trực tiếp tệp nhị phân

Nếu Docker không được phép trong môi trường của bạn, bạn có thể cài đặt và chạy trực tiếp tệp nhị phân server, tệp này sẽ sử dụng kho chứng chỉ hệ thống của bạn:

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

Phát triển

Điều kiện tiên quyết

  • Go (kiểm tra tệp go.mod để biết phiên bản cụ thể)
  • Docker (tùy chọn, để xây dựng container)

Các lệnh Make có sẵn

LệnhMô tả
make buildBiên dịch tệp nhị phân
make testChạy tất cả bài kiểm tra
make test-e2eChạy bài kiểm tra đầu cuối
make docker-buildXây dựng hình ảnh Docker
make run-httpChạy máy chủ HTTP cục bộ
make docker-run-httpChạy máy chủ HTTP trong Docker
make test-httpKiểm tra điểm cuối sức khỏe HTTP
make cleanXóa các tệp xây dựng
make helpHiển thị tất cả lệnh có sẵn

Đóng góp

  1. Fork kho lưu trữ
  2. Tạo nhánh tính năng của bạn
  3. Thực hiện các thay đổi của bạn
  4. Chạy bài kiểm tra
  5. Gửi yêu cầu kéo

Giấy phép

Dự án này được cấp phép theo các điều khoản của giấy phép nguồn mở MPL-2.0. Vui lòng tham khảo tệp LICENSE để biết đầy đủ các điều khoản.

Bảo mật

Đối với các vấn đề bảo mật, vui lòng liên hệ security@hashicorp.com hoặc tuân theo chính sách bảo mật của chúng tôi.

Hỗ trợ

Đối với báo cáo lỗi và yêu cầu tính năng, vui lòng mở một vấn đề trên GitHub.

Đối với câu hỏi chung và thảo luận, hãy mở một cuộc thảo luận trên GitHub.