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 trong Terraform Registry công khai — tìm providers và modules theo từ khóa bằng cách sử dụng search_providerssearch_modules.
  • Kiểm tra chi tiết provider và module — truy xuất tài liệu, phiên bản, và đầu vào/đầu ra với get_provider_detailsget_module_details.
  • Quản lý HCP Terraform / TFE workspaces — liệt kê, tạo, cập nhật và xóa workspaces, bao gồm biến và thẻ, thông qua list_workspaces và các công cụ liên quan.
  • Kiểm soát thực thi run — liệt kê các run, áp dụng hoặc hủy bỏ plans, và khóa/mở khóa workspaces bằng cách sử dụng các công cụ quản lý run.
  • Truy cập private registries — tìm kiếm và truy xuất chi tiết từ các registry provider và module riêng tư khi kết nối với Terraform Enterprise.

Tài liệu

Terraform MCP Server

Terraform MCP Server là một máy chủ Model Context Protocol (MCP) cung cấp khả năng tích hợp liền mạch với các API của Terraform Registry, cho phép tự động hóa nâng cao và khả năng tương tác cho phát triển Cơ sở hạ tầng dưới dạng Mã (IaC).

Tính năng

  • Hỗ trợ truyền tải kép: Cả hai phương thức 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 nhà cung cấp, mô-đun và chính sách
  • Hỗ trợ HCP Terraform & Terraform Enterprise: Quản lý không gian làm việc đầy đủ, liệt kê tổ chức/dự án và truy cập registry riêng tư
  • Thao tác với không gian làm việc: Tạo, cập nhật, xóa không gian làm việc với hỗ trợ biến, thẻ và quản lý lần chạy
  • Số liệu OTel để giám sát việc sử dụng công cụ: Tích hợp với các đồng hồ đo telemetry mở để theo dõi khối lượng, độ trễ và lỗi của lệnh gọi công cụ trong chế độ Streamable HTTP. Cũng hiển thị các số liệu 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ể tiết lộ một số dữ liệu Terraform 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 Máy khách/LLM MCP 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 đảm và trách nhiệm pháp lý đối với Máy khách/LLM MCP 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 dựa trên 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 container.
  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ỉ; nó không thể được cung cấp bởi máy khách qua tiêu đề hoặc tham số truy vấn.Tùy chọn
TFE_TOKENMã thông báo API Terraform Enterprise"" (trống)
TFE_SKIP_TLS_VERIFYBỏ qua xác minh TLS của HCP Terraform hoặc Terraform Enterprisefalse
LOG_LEVELMức ghi nhật ký: trace, debug, info, warn, error, fatal, panic (ghi đè cờ --log-level)info
LOG_FORMATĐịnh dạng ghi nhật ký: 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ị cũ http 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 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 các nguồn gốc được phép cho CORS, phân tách bằng dấu phẩy"" (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, cần thiết 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, cần thiết 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ục (đị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 lấy IP máy khách khi chuyển tiếp được bật: 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 đáng tin cậy được tính 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à số liệu máy chủ sử dụng otelfalse
OTEL_METRICS_SERVICE_VERSIONPhiên bản của terraform-mcp-server gửi số liệu, được sử dụng để đặt thuộc tính số liệu. Nó cũng giúp theo dõi số liệu trên các lần triển khai khác nhaulatest
OTEL_METRICS_SERVICE_NAMEXác định nguồn của số liệu (ví dụ: "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALKiểm soát tần suất xả số liệu2
OTEL_METRICS_ENDPOINTURL của Bộ thu thập OTel hoặc backend của bạnlocalhost:4318
INSTANA_ENABLEDBật thiết bị đo Instana (số liệu và theo dõi yêu cầu HTTP) cho máy chủ streamable-http. Yêu cầu một tác nhân Instana mà máy chủ có thể truy cập được.false
# 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 trong cmd/terraform-mcp-server/instructions.md, nếu những hướng dẫn đó có vẻ không phù hợp với thực tiễn 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 tệp nhị phân. Một ví dụ về hướng dẫn như vậy nằm trong instructions/example-mcp-instructions.md

AGENTS.md về cơ bản hoạt động như README cho các tác nhân 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 tác nhân 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 tác nhân mã hóa khác nhau. Một ví dụ về hướng dẫn như vậy nằm trong 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 chứa 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 Cài đặt Người dùng (JSON) của bạn trong VS Code. Bạn có thể thực hiện việc này bằng cách nhấn Ctrl + Shift + P và nhập Preferences: Open User Settings (JSON).

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

Phiên bản 0.3.0 trở lênPhiên bản 0.2.3 trở xuống
{
  "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"
        ]
      }
    }
  }
}

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 không gian làm việc 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 trở lênPhiên bản 0.2.3 trở xuống
{
  "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"
      ]
    }
  }
}

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

Sử dụng với Cursor

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

Phiên bản 0.3.0 trở lênPhiên bản 0.2.3 trở xuống
{
  "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"
      ]
    }
  }
}
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ụ máy chủ MCP trong tài liệu người dùng Claude Desktop. Đọc thêm về cách sử dụng máy chủ MCP trong Amazon Q DeveloperKiro CLI.

Phiên bản 0.3.0 trở lênPhiên bản 0.2.3 trở xuống
{
  "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"
      ]
    }
  }
}

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ụ máy chủ MCP trong tài liệu người dùng Claude Code

  • Truyền tải Cục bộ (stdio)
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Truyền tải 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 tiện ích mở rộng Gemini

Để 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 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ụ máy chủ MCP trong Bob IDE hoặc Shell Sử dụng MCP trong Bob.

Phiên bản 0.3.0 trở lênPhiên bản 0.2.3 trở xuống
{
  "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
    }
  }
}

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 trở lênPhiên bản 0.2.3 trở xuống
{
  "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 máy chủ, 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ông cụ Có sẵn

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

Tài nguyên Có sẵn

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

Số liệu Có sẵn

Hai loại số liệu được thu thập. Đầu tiên, các số liệu máy chủ HTTP tiêu chuẩn được thêm vào bằng cách bao bọc bộ ghép kênh HTTP 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, máy chủ MCP ghi lại các số liệu công cụ tùy chỉnh xung quanh việc thực thi công cụ bằng cách sử dụng các hook MCP (BeforeCallTool / AfterCallTool). Những số liệu 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 những công cụ nào có sẵn bằng cách sử dụng --toolsets (nhóm) hoặc --tools (cá nhân):

# 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

Bộ công cụ khả dụng: 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ợ Giao thức Truyền tải

Terraform MCP Server hỗ trợ nhiều giao thức truyền tải:

1. Giao thức Stdio (Mặc định)

Giao tiếp đầu vào/đầu ra tiêu chuẩn sử dụng các 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 máy khách MCP.

2. Giao thức StreamableHTTP

Giao thức truyền tải 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à giao thức được khuyến nghị cho các thiết lập từ xa/phân tán.

Tính năng:

  • Điểm cuối: http://{hostname}:8080/mcp
  • Kiểm tra tình trạng: 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 làm việc

Terraform MCP Server hỗ trợ hai chế độ phiên khi sử dụng giao thức 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 thao tác 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, điều này có thể hữu ích cho các triển khai có tính sẵn sàng cao hoặc khi sử dụng bộ cân bằng tải.

Để bật chế độ không trạng thái, hãy đặt biến môi trường:

export MCP_SESSION_MODE=stateless

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

Khi chạy máy chủ MCP 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 tiêu đề HTTP để thực thi RBAC. Điều này cho phép một phiên bản máy chủ 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. Máy chủ 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 CSV cho phép. 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, máy chủ sẽ thoát với lỗi danh sách cho phép tổ chức không đúng định dạng.

Chuyển tiếp IP Máy khách

Khi chạy máy chủ MCP 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 máy khách 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 bật bằng MCP_FORWARD_CLIENT_IP=true.

Khi được bật, máy chủ lấy IP máy khách 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ẽ quay lại dùng RemoteAddr.
X-Forwarded-ForSử dụng chuỗi X-Forwarded-For, chọn mục ở vị trí MCP_XFF_TRUSTED_HOPS tính từ bên phải. Quay lại dùng 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 máy khách 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 máy chủ ghi đè lên chúng. Vì lý do này, mặc định là RemoteAddr, chỉ tin cậy peer mà máy chủ được kết nối trực tiếp. Chỉ bật X-Real-IP hoặc X-Forwarded-For khi máy chủ nằm sau một proxy mà bạn kiểm soát và proxy đó đặt các tiêu đề này.

Số bước nhảy tin cậy

Khi sử dụng X-Forwarded-For, MCP_XFF_TRUSTED_HOPS là số lượng proxy bạn vận hành giữa máy chủ và internet. Các bước nhảy được đếm từ bên phải của chuỗi, vì mỗi proxy thêm địa chỉ mà nó nhận được yêu cầu từ đó và mục ngoài cùng bên phải được đặt bởi proxy gần máy chủ nhất. Máy chủ bỏ qua số mục 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, máy chủ 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, hoặc mục được chọn không phải là IP hợp lệ, máy chủ sẽ quay lại dùng RemoteAddr.

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

Hạn chế

  • Máy chủ 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, nhưng thư viện chuẩn của Go chỉ trả về tiêu đề đầu tiên và máy chủ 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 là IP hợp lệ sẽ bị từ chối và máy chủ quay lại dùng 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 đề hiện diện, 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 là giá trị dễ bị giả mạo nhất. Mặc định hiện tại là RemoteAddr. Nếu bạn chạy máy chủ 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 thành số lượng proxy bạn vận hành.

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 máy khách. Trong chế độ streamable-http, địa chỉ Terraform chỉ được lấy từ biến môi trường TFE_ADDRESS phía máy chủ (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 lỗi 403. Điều này ngăn máy khách chuyển hướng yêu cầu và token Authorization đến một máy chủ độc hại.
  • Không bao giờ truyền token trong tham số truy vấn - máy chủ 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ế những máy khách 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.1.0

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

Khắc phục sự cố

Proxy Công ty / Kiểm tra TLS (Zscaler, v.v.)

Nếu bạn đứng sau proxy công ty thực hiện kiểm tra TLS (như Zscaler Internet Access), bạn có thể thấy 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ông ty của 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.1.0

Đối với cấu hình máy khách 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"
      ]
    }
  }
}

Giải pháp 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 máy chủ, nó 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 Khả dụng

LệnhMô tả
make buildXây dựng tệp nhị phân
make testChạy tất cả các bài kiểm tra
make test-e2eChạy các bài kiểm tra end-to-end
make docker-buildXây dựng image 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 health HTTP
make cleanXóa các tạo phẩm build
make helpHiển thị tất cả các lệnh khả dụng

Đó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 các bài kiểm tra
  5. Gửi pull request

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 các điều khoản đầy đủ.

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 làm 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 issue trên GitHub.

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