Terraform MCP Server
chính thứcMá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_providersvàget_provider_detailstừ 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ờ
--toolsetshoặc--toolsnhư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 Registry và HCP 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
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
- Đảm bảo Docker được cài đặt và đang chạy để sử dụng máy chủ trong môi trường containerized.
- 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ến | Mô 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_TOKEN | Token API Terraform Enterprise | "" (trống) |
TF_MCP_SHARED_SECRET | Bí 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_VERIFY | Bỏ qua xác minh TLS của HCP Terraform hoặc Terraform Enterprise | false |
LOG_LEVEL | Mứ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_HOST | Máy chủ để liên kết máy chủ HTTP | 127.0.0.1 |
TRANSPORT_PORT | Cổng máy chủ HTTP | 8080 |
MCP_ENDPOINT | Đường dẫn điểm cuối máy chủ HTTP | /mcp |
MCP_REDIRECT_ROOT_URL | URL để chuyển hướng các yêu cầu đến / | "" |
MCP_KEEP_ALIVE | Khoảng thời gian keep-alive cho các kết nối SSE (ví dụ: 30s, 1m). 0 để tắt | 0 |
MCP_SESSION_MODE | Chế độ phiên: stateful hoặc stateless | stateful |
MCP_ALLOWED_ORIGINS | Danh 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_MODE | Chế độ CORS: strict, development, hoặc disabled | strict |
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_GLOBAL | Giới hạn tốc độ toàn cầu (định dạng: rps:burst) | 10:20 |
MCP_RATE_LIMIT_SESSION | Giới hạn tốc độ mỗi phiên (định dạng: rps:burst) | 5:10 |
MCP_ORGANIZATION_ALLOWLIST | Danh 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_IP | Chuyển tiếp IP máy khách đến HCP Terraform / TFE qua X-Forwarded-For. Đặt thành true để bật | false |
MCP_REMOTE_IP_METHOD | Cá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-For | RemoteAddr |
MCP_XFF_TRUSTED_HOPS | Số 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-For | 0 |
ENABLE_TF_OPERATIONS | Bật các công cụ yêu cầu phê duyệt rõ ràng | false |
OTEL_METRICS_ENABLED | Bật các công cụ và chỉ số máy chủ sử dụng otel | false |
OTEL_METRICS_SERVICE_VERSION | Phiê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 nhau | latest |
OTEL_METRICS_SERVICE_NAME | Xác định nguồn của chỉ số (ví dụ: "terraform-mcp-server") | terraform-mcp-server |
OTEL_METRICS_EXPORT_INTERVAL | Kiểm soát tần suất xả chỉ số | 2 |
OTEL_METRICS_ENDPOINT | URL của OTel Collector hoặc backend của bạn | localhost:4318 |
INSTANA_ENABLED | Bậ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_NAME | Nếu bật công cụ Instana instrumentation, tên dịch vụ để sử dụng cho máy chủ 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>]
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ơn | Phiên bản 0.2.3 hoặc thấp hơn |
|---|---|
|
|
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ơn | Phiên bản 0.2.3 hoặc thấp hơn |
|---|---|
|
|
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ơn | Phiên bản 0.2.3 hoặc thấp hơn |
|---|---|
|
|
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 Developer và Kiro CLI.
| Phiên bản 0.3.0+ hoặc mới hơn | Phiên bản 0.2.3 hoặc cũ hơn |
|---|---|
|
|
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_ADDRESSvàTFE_TOKENvà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ơn | Phiên bản 0.2.3 hoặc cũ hơn |
|---|---|
|
|
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ơn | Phiên bản 0.2.3 hoặc cũ hơn |
|---|---|
|
|
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ộ:
- Sao chép kho lưu trữ:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
- Xây dựng Docker image:
make docker-build
- 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.
- (Tùy chọn) Kiểm tra kết nối ở chế độ http
# Test the connection
curl http://localhost:8080/health
- 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:
- http.server.request.body.size
- http.server.response.body.size
- 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:
- mcp_tool_calls_total
- mcp_tool_errors_total
- 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=httphoặcTRANSPORT_PORT=8080để kích hoạt - Danh sách cho phép tổ chức: Đặt
MCP_ORGANIZATION_ALLOWLISThoặc--organization-allowlistthà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ức | Hà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-For và X-Real-IP. |
X-Real-IP | Sử 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-For | Sử 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-For và X-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=2 và 108.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-Forlà 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-Forkế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-For và MCP_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_TOKEN | Token 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_VERIFY | Bỏ 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_ADDRESSphía server (hoặc mặc định). Các yêu cầu cố gắng đặtTFE_ADDRESSqua 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à tokenAuthorizationđến một server độc hại. - Nhận dạng triển khai được lưu trữ: việc đặt
TF_MCP_SHARED_SECRETsẽ gửi giá trị đó làm tiêu đềX-Tf-Mcp-Secrettrê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ệnh | Mô tả |
|---|---|
make build | Biên dịch tệp nhị phân |
make test | Chạy tất cả bài kiểm tra |
make test-e2e | Chạy bài kiểm tra đầu cuối |
make docker-build | Xây dựng hình ảnh Docker |
make run-http | Chạy máy chủ HTTP cục bộ |
make docker-run-http | Chạy máy chủ HTTP trong Docker |
make test-http | Kiểm tra điểm cuối sức khỏe HTTP |
make clean | Xóa các tệp xây dựng |
make help | Hiển thị tất cả lệnh có sẵn |
Đóng góp
- Fork kho lưu trữ
- Tạo nhánh tính năng của bạn
- Thực hiện các thay đổi của bạn
- Chạy bài kiểm tra
- 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.