Terraform MCP Server

resmi

Server MCP HashiCorp Terraform untuk alur kerja Infrastructure as Code, termasuk penemuan penyedia dan modul melalui Terraform Registry.

Apa yang bisa Anda lakukan dengan Terraform MCP?

  • Cari Terraform Registry — Minta untuk menemukan provider atau modul menggunakan search_providers dan get_provider_details dari registry publik.
  • Kelola workspace HCP Terraform — Buat, perbarui, atau hapus workspace serta tangani variabel, tag, dan run melalui operasi workspace.
  • Daftarkan organisasi dan proyek — Ambil daftar organisasi dan proyek dari HCP Terraform atau Terraform Enterprise.
  • Akses konten registry privat — Kueri provider, modul, dan kebijakan registry privat dengan perangkat registry-private.
  • Filter alat yang tersedia — Aktifkan hanya kemampuan yang diperlukan menggunakan flag --toolsets atau --tools seperti list_workspaces.

Dokumentasi

Terraform MCP Server

Terraform MCP Server adalah server Model Context Protocol (MCP) yang terintegrasi secara mulus dengan API Terraform Registry dan HCP Terraform, memungkinkan kemampuan otomatisasi dan interaksi tingkat lanjut untuk pengembangan Infrastructure as Code (IaC).

Daftar Isi

MemulaiIntegrasi KlienMembangun dan Menjalankan
Fitur
Prasyarat
Opsi Baris Perintah
Instruksi
Instalasi
Visual Studio Code
Cursor
Claude Desktop, Amazon Q Developer, dan Kiro CLI
Claude Code
Codex CLI
Ekstensi Gemini
Bob IDE dan Shell
Instal dari sumber
Membangun Image Docker secara lokal
Dukungan Transport
Transport Stdio
Transport StreamableHTTP
Kapabilitas ServerPenerapan dan keamananBantuan dan kontribusi
Alat yang Tersedia
Sumber Daya yang Tersedia
Metrik yang Tersedia
Pemfilteran Alat
Mode Sesi
Penerusan Token untuk Penerapan Terpusat
Penerusan IP Klien
Model kepercayaan
Lompatan tepercaya
Keterbatasan
Migrasi dari versi sebelumnya
Header yang Didukung
Pertimbangan Keamanan
Contoh Penerapan Terpusat
Pemecahan Masalah
Proxy Perusahaan dan Inspeksi TLS
Pengembangan
Kontribusi
Lisensi
Keamanan
Dukungan

Fitur

  • Dukungan Transport Ganda: Transport Stdio dan StreamableHTTP dengan endpoint yang dapat dikonfigurasi
  • Integrasi Terraform Registry: Integrasi langsung dengan API Terraform Registry publik untuk provider, modul, dan kebijakan
  • Dukungan HCP Terraform & Terraform Enterprise: Manajemen workspace lengkap, daftar organisasi/proyek, dan akses registry privat
  • Operasi Workspace: Buat, perbarui, hapus workspace dengan dukungan untuk variabel, tag, dan manajemen run
  • Metrik OTel untuk pemantauan penggunaan alat: Integrasi dengan meter open telemetry untuk melacak volume panggilan alat, latensi, dan kegagalan dalam mode Streamable HTTP. Juga mengekspos metrik server http default saat fitur ini diaktifkan

Catatan Keamanan: Tergantung pada kueri, server MCP dapat mengekspos data Terraform tertentu ke klien MCP dan LLM. Jangan gunakan server MCP dengan klien MCP atau LLM yang tidak tepercaya.

Catatan Hukum: Penggunaan Anda atas Klien MCP/LLM pihak ketiga tunduk semata-mata pada ketentuan penggunaan MCP/LLM tersebut, dan IBM tidak bertanggung jawab atas kinerja alat pihak ketiga tersebut. IBM secara tegas menolak segala jaminan dan tanggung jawab atas Klien MCP/LLM pihak ketiga, dan mungkin tidak dapat memberikan dukungan untuk menyelesaikan masalah yang disebabkan oleh alat pihak ketiga.

Perhatian: Output dan rekomendasi yang diberikan oleh server MCP dihasilkan secara dinamis dan dapat bervariasi berdasarkan kueri, model, dan klien MCP yang terhubung. Pengguna harus meninjau secara menyeluruh semua output/rekomendasi untuk memastikan bahwa output/rekomendasi tersebut selaras dengan praktik keamanan terbaik organisasi, tujuan efisiensi biaya, dan persyaratan kepatuhan sebelum implementasi.

Prasyarat

  1. Pastikan Docker terinstal dan berjalan untuk menggunakan server dalam lingkungan kontainer.
  2. Instal asisten AI yang mendukung Model Context Protocol (MCP).

Opsi Baris Perintah

Variabel Lingkungan:

VariabelDeskripsiDefault
TFE_ADDRESSMengatur alamat Terraform Enterprise/HCP Terraform untuk panggilan API. Harus menyertakan protokol (misalnya, https://app.terraform.io). Dalam mode streamable-http ini adalah satu-satunya cara untuk mengatur alamat; tidak dapat diberikan oleh klien melalui header atau parameter kueri.Opsional
TFE_TOKENToken API Terraform Enterprise"" (kosong)
TF_MCP_SHARED_SECRETRahasia bersama yang dikirim sebagai header X-Tf-Mcp-Secret pada permintaan ke HCP Terraform / TFE, digunakan untuk mengidentifikasi permintaan yang berasal dari penerapan MCP yang dihosting. Hanya boleh digunakan melalui TLS."" (kosong)
TFE_SKIP_TLS_VERIFYLewati verifikasi TLS HCP Terraform atau Terraform Enterprisefalse
LOG_LEVELTingkat pencatatan: trace, debug, info, warn, error, fatal, panic (menimpa flag --log-level)info
LOG_FORMATFormat pencatatan: text atau json (menimpa flag --log-format)text
TRANSPORT_MODEAtur ke streamable-http untuk mengaktifkan transport HTTP (nilai legacy http masih didukung)stdio
TRANSPORT_HOSTHost untuk mengikat server HTTP127.0.0.1
TRANSPORT_PORTPort server HTTP8080
MCP_ENDPOINTJalur endpoint server HTTP/mcp
MCP_REDIRECT_ROOT_URLURL untuk mengarahkan permintaan ke /""
MCP_KEEP_ALIVEInterval keep-alive untuk koneksi SSE (misalnya, 30s, 1m). 0 untuk menonaktifkan0
MCP_SESSION_MODEMode sesi: stateful atau statelessstateful
MCP_ALLOWED_ORIGINSDaftar asal yang diizinkan untuk CORS, dipisahkan koma"" (kosong)
MCP_CORS_MODEMode CORS: strict, development, atau disabledstrict
MCP_TLS_CERT_FILEJalur ke file sertifikat TLS, diperlukan untuk penerapan non-localhost (misalnya /path/to/cert.pem)"" (kosong)
MCP_TLS_KEY_FILEJalur ke file kunci TLS, diperlukan untuk penerapan non-localhost (misalnya /path/to/key.pem)"" (kosong)
MCP_RATE_LIMIT_GLOBALBatas laju global (format: rps:burst)10:20
MCP_RATE_LIMIT_SESSIONBatas laju per sesi (format: rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTDaftar CSV nama organisasi HCP Terraform yang diizinkan mengakses server HTTP"" (kosong)
MCP_FORWARD_CLIENT_IPTeruskan IP klien ke HCP Terraform / TFE melalui X-Forwarded-For. Atur ke true untuk mengaktifkanfalse
MCP_REMOTE_IP_METHODCara IP klien bersumber saat penerusan diaktifkan: RemoteAddr (koneksi langsung saja), X-Real-IP, atau X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSJumlah lompatan proxy tepercaya yang dihitung dari kanan rantai X-Forwarded-For. Hanya digunakan saat MCP_REMOTE_IP_METHOD=X-Forwarded-For0
ENABLE_TF_OPERATIONSAktifkan alat yang memerlukan persetujuan eksplisitfalse
OTEL_METRICS_ENABLEDAktifkan alat dan metrik server menggunakan otelfalse
OTEL_METRICS_SERVICE_VERSIONVersi terraform-mcp-server yang mengirim metrik, yang digunakan untuk mengatur atribut metrik. Ini juga membantu melacak metrik di berbagai penerapanlatest
OTEL_METRICS_SERVICE_NAMEMengidentifikasi sumber metrik (misalnya, "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALMengontrol frekuensi pembilasan metrik2
OTEL_METRICS_ENDPOINTURL OTel Collector atau backend Andalocalhost:4318
INSTANA_ENABLEDAktifkan instrumentasi Instana (metrik dan pelacakan permintaan HTTP) untuk server streamable-http. Memerlukan agen Instana yang dapat dijangkau oleh server.false
INSTANA_SERVICE_NAMEJika instrumentasi Instana diaktifkan, nama layanan yang digunakan untuk server 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>]

Instruksi

Instruksi default untuk server MCP terletak di cmd/terraform-mcp-server/instructions.md. Jika instruksi tersebut tidak sesuai dengan praktik Terraform organisasi Anda atau jika server MCP menghasilkan respons yang tidak akurat, silakan ganti dengan instruksi Anda sendiri dan bangun ulang kontainer atau biner. Contoh instruksi tersebut terletak di instructions/example-mcp-instructions.md

AGENTS.md pada dasarnya berperilaku seperti README untuk agen pengkodean: tempat yang khusus dan dapat diprediksi untuk memberikan konteks dan instruksi guna membantu agen pengkodean AI bekerja pada proyek Anda. Satu file AGENTS.md berfungsi dengan berbagai agen pengkodean. Contoh instruksi tersebut terletak di instructions/example-AGENTS.md. Untuk menggunakannya, lakukan commit file bernama AGENTS.md ke direktori tempat konfigurasi Terraform Anda berada.

Instalasi

Penggunaan dengan Visual Studio Code

Tambahkan blok JSON berikut ke file User Settings (JSON) Anda di VS Code. Anda dapat melakukannya dengan menekan Ctrl + Shift + P dan mengetik Preferences: Open User Settings (JSON).

Lebih lanjut tentang penggunaan alat server MCP di dokumentasi mode agen VS Code.

Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih rendah
{
  "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"
        ]
      }
    }
  }
}

Secara opsional, Anda dapat menambahkan contoh serupa (yaitu tanpa kunci mcp) ke file bernama .vscode/mcp.json di workspace Anda. Ini akan memungkinkan Anda berbagi konfigurasi dengan orang lain.

Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih rendah
{
  "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)

Penggunaan dengan Cursor

Tambahkan ini ke konfigurasi Cursor Anda (~/.cursor/mcp.json) atau melalui Settings → Cursor Settings → MCP:

Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih rendah
{
  "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

Penggunaan dengan Claude Desktop / Amazon Q Developer / Kiro CLI

Pelajari lebih lanjut tentang penggunaan alat MCP server di Claude Desktop dokumentasi pengguna. Baca lebih lanjut tentang penggunaan MCP server di Amazon Q Developer dan Kiro CLI.

Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih lama
{
  "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"
      ]
    }
  }
}

Penggunaan dengan Claude Code

Pelajari lebih lanjut tentang penggunaan dan penambahan alat MCP server di Claude Code dokumentasi pengguna

  • Transport Lokal (stdio)
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Transport Jarak Jauh (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

Penggunaan dengan Codex CLI

Pelajari lebih lanjut tentang penggunaan dan penambahan alat MCP server di Codex CLI dokumentasi pengguna.

Catatan: Tambahkan TFE_ADDRESS dan TFE_TOKEN ke perintah Docker untuk alat HCP Terraform atau Terraform Enterprise yang terautentikasi.

  • Transport Lokal (stdio)
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server
  • Transport Jarak Jauh (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

Penggunaan dengan ekstensi Gemini

Demi keamanan, hindari menuliskan kredensial secara langsung, buat atau perbarui ~/.gemini/.env (di mana ~ adalah direktori rumah atau proyek Anda) untuk menyimpan kredensial HCP Terraform atau Terraform Enterprise

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

Instal ekstensi & jalankan Gemini

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

Penggunaan dengan Bob IDE / Shell

Pelajari lebih lanjut tentang penggunaan dan penambahan alat MCP server di Bob IDE atau Shell Menggunakan MCP di Bob.

Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih lama
{
  "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
    }
  }
}

Instal dari sumber

Gunakan versi rilis terbaru:

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

Gunakan cabang utama:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Versi 0.3.0+ atau lebih baruVersi 0.2.3 atau lebih lama
{
  "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"
      }
    }
  }
}

Membangun Image Docker secara Lokal

Sebelum menggunakan server, Anda perlu membangun image Docker secara lokal:

  1. Klon repositori:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Bangun image Docker:
make docker-build
  1. Ini akan membuat image Docker lokal yang dapat Anda gunakan dalam konfigurasi berikut.
# 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

Catatan: Saat dijalankan di Docker, Anda harus mengatur TRANSPORT_HOST=0.0.0.0 untuk mengizinkan koneksi dari luar kontainer.

  1. (Opsional) Uji koneksi dalam mode http
# Test the connection
curl http://localhost:8080/health
  1. Anda dapat menggunakannya pada asisten AI Anda sebagai berikut:
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Alat yang Tersedia

Lihat alat yang tersedia di sini :link:

Sumber Daya yang Tersedia

Lihat sumber daya yang tersedia di sini :link:

Metrik yang Tersedia

Dua jenis metrik dikumpulkan. Pertama, metrik server HTTP standar ditambahkan dengan membungkus mux HTTP dengan otelhttp.NewHandler(...). Ini menghasilkan:

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

Kedua, server MCP mencatat metrik alat kustom di sekitar eksekusi alat menggunakan hook MCP (BeforeCallTool / AfterCallTool). Ini menghasilkan:

  1. mcp_tool_calls_total
  2. mcp_tool_errors_total
  3. mcp_tool_duration_seconds

Pemfilteran Alat

Kontrol alat mana yang tersedia menggunakan --toolsets (grup) atau --tools (individu):

# 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

Toolset yang tersedia: registry, registry-private, terraform, all, default. Lihat pkg/toolsets/mapping.go untuk nama alat individu. Tidak dapat menggunakan kedua flag secara bersamaan.

Dukungan Transport

Terraform MCP Server mendukung beberapa protokol transport:

1. Transport Stdio (Default)

Komunikasi input/output standar menggunakan pesan JSON-RPC. Ideal untuk pengembangan lokal dan integrasi langsung dengan klien MCP.

2. Transport StreamableHTTP

Transport berbasis HTTP modern yang mendukung permintaan HTTP langsung dan aliran Server-Sent Events (SSE). Ini adalah transport yang direkomendasikan untuk pengaturan jarak jauh/terdistribusi.

Fitur:

  • Endpoint: http://{hostname}:8080/mcp
  • Pemeriksaan Kesehatan: http://{hostname}:8080/health
  • Konfigurasi Lingkungan: Atur TRANSPORT_MODE=http atau TRANSPORT_PORT=8080 untuk mengaktifkan
  • Daftar Izin Organisasi: Atur MCP_ORGANIZATION_ALLOWLIST atau --organization-allowlist ke daftar CSV nama organisasi HCP Terraform yang diizinkan

Mode Sesi

Terraform MCP Server mendukung dua mode sesi saat menggunakan transport StreamableHTTP:

  • Mode Stateful (Default): Mempertahankan status sesi antar permintaan, memungkinkan operasi yang sadar konteks.
  • Mode Stateless: Setiap permintaan diproses secara independen tanpa mempertahankan status sesi, yang dapat berguna untuk penerapan ketersediaan tinggi atau saat menggunakan penyeimbang beban.

Untuk mengaktifkan mode stateless, atur variabel lingkungan:

export MCP_SESSION_MODE=stateless

Penerusan Token untuk Penerapan Terpusat

Saat menjalankan server MCP secara terpusat (mode StreamableHTTP) untuk banyak pengguna, setiap pengguna dapat meneruskan token Terraform mereka sendiri melalui header HTTP untuk penegakan RBAC. Ini memungkinkan satu instance server melayani banyak pengguna dengan izin berbeda.

Saat MCP_ORGANIZATION_ALLOWLIST atau --organization-allowlist dikonfigurasi, daftar izin harus berupa daftar CSV nama organisasi HCP Terraform. Server memerlukan Authorization: Bearer <token> dan menolak permintaan kecuali token tersebut dapat mengakses setidaknya satu organisasi dalam daftar izin CSV. Token pembawa memiliki prioritas jika permintaan juga menyertakan header TFE_TOKEN, memastikan token yang divalidasi oleh daftar izin adalah token yang digunakan untuk permintaan API Terraform. Pencocokan nama organisasi tidak peka huruf besar/kecil. Jika nilai CSV yang dikonfigurasi diurai menjadi nol nama organisasi, server keluar dengan kesalahan daftar izin organisasi yang salah format.

Penerusan IP Klien

Saat menjalankan server MCP secara terpusat di belakang proxy atau penyeimbang beban, Anda dapat meneruskan IP klien asal ke HCP Terraform / TFE melalui header X-Forwarded-For. Ini nonaktif secara default dan harus diaktifkan dengan MCP_FORWARD_CLIENT_IP=true.

Saat diaktifkan, server mengambil IP klien sesuai dengan MCP_REMOTE_IP_METHOD:

MetodePerilaku
RemoteAddr (default)Hanya menggunakan alamat koneksi TCP langsung. Mengabaikan X-Forwarded-For dan X-Real-IP.
X-Real-IPMenggunakan header X-Real-IP jika merupakan IP yang valid, jika tidak, kembali ke RemoteAddr.
X-Forwarded-ForMenggunakan rantai X-Forwarded-For, memilih entri MCP_XFF_TRUSTED_HOPS posisi dari kanan. Kembali ke RemoteAddr jika nilainya hilang atau tidak valid.

Model kepercayaan

X-Forwarded-For dan X-Real-IP diatur oleh klien dan proxy perantara, sehingga dapat dipalsukan kecuali proxy tepercaya di depan server menimpanya. Karena alasan ini, defaultnya adalah RemoteAddr, yang hanya mempercayai rekan yang terhubung langsung ke server. Hanya aktifkan X-Real-IP atau X-Forwarded-For saat server berada di belakang proxy yang Anda kendalikan yang mengatur header ini.

Hop tepercaya

Saat menggunakan X-Forwarded-For, MCP_XFF_TRUSTED_HOPS adalah jumlah proxy yang Anda operasikan antara server dan internet. Hop dihitung dari kanan rantai, karena setiap proxy menambahkan alamat tempat ia menerima permintaan dan entri paling kanan diatur oleh proxy yang paling dekat dengan server. Server melewati jumlah entri tepercaya tersebut dan mengambil entri berikutnya ke kiri.

Misalnya, dengan MCP_XFF_TRUSTED_HOPS=1 dan header 200.1.2.3, 10.1.1.10, server memilih 200.1.2.3. Dengan MCP_XFF_TRUSTED_HOPS=2 dan 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1, ia memilih 200.1.2.3. Jika jumlah hop lebih besar dari jumlah entri, atau entri yang dipilih bukan IP yang valid, server kembali ke RemoteAddr.

Mengatur jumlah hop terlalu rendah akan mempercayai nilai yang disediakan klien; mengaturnya terlalu tinggi akan mempercayai alamat yang lebih jauh ke dalam infrastruktur Anda sendiri. Atur ke jumlah persis proxy yang Anda jalankan.

Keterbatasan

  • Server hanya membaca header X-Forwarded-For pertama pada permintaan. Valid untuk permintaan membawa beberapa header X-Forwarded-For, tetapi pustaka standar Go hanya mengembalikan yang pertama, dan server tidak menggabungkannya. Jika rantai proxy Anda mengeluarkan beberapa header, konfigurasikan untuk mengeluarkan satu header X-Forwarded-For gabungan.
  • Alamat IPv4 dan IPv6 keduanya didukung. Nilai yang bukan IP valid ditolak dan server kembali ke RemoteAddr.

Migrasi dari versi sebelumnya

Versi sebelumnya menggunakan nilai X-Forwarded-For paling kiri saat header ada, tanpa konfigurasi. Ini tidak aman, karena nilai paling kiri paling mudah dipalsukan. Defaultnya sekarang adalah RemoteAddr. Jika Anda menjalankan server di belakang proxy dan mengandalkan X-Forwarded-For untuk diteruskan ke HCP Terraform / TFE, atur MCP_REMOTE_IP_METHOD=X-Forwarded-For dan MCP_XFF_TRUSTED_HOPS ke jumlah proxy yang Anda operasikan.

Header yang Didukung

HeaderDeskripsi
TFE_TOKENToken API Terraform
Authorization: Bearer <token>Metode alternatif menggunakan autentikasi Bearer standar
TFE_SKIP_TLS_VERIFYLewati verifikasi TLS untuk permintaan

Contoh: 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",...}'

Pertimbangan Keamanan

  • TFE_ADDRESS tidak dapat diatur oleh klien. Dalam mode streamable-http, alamat Terraform hanya diambil dari variabel lingkungan TFE_ADDRESS sisi server (atau default). Permintaan yang mencoba mengatur TFE_ADDRESS melalui header HTTP atau parameter kueri ditolak dengan 403. Ini mencegah klien mengarahkan ulang permintaan, dan token Authorization, ke server berbahaya.
  • Identifikasi penerapan yang dihosting: mengatur TF_MCP_SHARED_SECRET mengirimkan nilai tersebut sebagai header X-Tf-Mcp-Secret pada setiap permintaan HCP Terraform / TFE, memungkinkan backend mengidentifikasi permintaan dari penerapan yang dihosting yang dikenal (misalnya untuk menerapkan daftar izin IP). Ini adalah rahasia statis yang dikirim dalam header, jadi hanya gunakan melalui TLS dan perlakukan nilainya sebagai kredensial.
  • Jangan pernah meneruskan token dalam parameter kueri - server akan menolak permintaan tersebut dengan kesalahan 400.
  • Selalu gunakan TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) saat menerapkan secara terpusat untuk melindungi token selama transmisi.
  • Konfigurasikan MCP_ALLOWED_ORIGINS untuk membatasi klien mana yang dapat terhubung.

Contoh Penerapan Terpusat

# 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

Pengguna kemudian terhubung dengan token individu mereka yang diteruskan melalui header, memungkinkan penegakan RBAC per pengguna.

Pemecahan Masalah

Proxy Perusahaan / Inspeksi TLS (Zscaler, dll.)

Jika Anda berada di belakang proxy perusahaan yang melakukan inspeksi TLS (seperti Zscaler Internet Access), Anda mungkin melihat kesalahan sertifikat:

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

Solusi: Pasang sertifikat CA perusahaan Anda ke dalam kontainer:

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

Untuk konfigurasi klien 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"
      ]
    }
  }
}

Alternatif: Jalankan biner secara langsung

Jika Docker tidak diizinkan di lingkungan Anda, Anda dapat menginstal dan menjalankan biner server secara langsung, yang akan menggunakan penyimpanan sertifikat sistem Anda:

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

Pengembangan

Prasyarat

  • Go (periksa file go.mod untuk versi spesifik)
  • Docker (opsional, untuk pembuatan kontainer)

Perintah Make yang Tersedia

PerintahDeskripsi
make buildMembangun biner
make testMenjalankan semua tes
make test-e2eMenjalankan tes end-to-end
make docker-buildMembangun image Docker
make run-httpMenjalankan server HTTP secara lokal
make docker-run-httpMenjalankan server HTTP di Docker
make test-httpMenguji endpoint kesehatan HTTP
make cleanMenghapus artefak build
make helpMenampilkan semua perintah yang tersedia

Berkontribusi

  1. Fork repositori
  2. Buat cabang fitur Anda
  3. Lakukan perubahan Anda
  4. Jalankan tes
  5. Kirim pull request

Lisensi

Proyek ini dilisensikan di bawah ketentuan lisensi open source MPL-2.0. Silakan merujuk ke file LICENSE untuk ketentuan lengkap.

Keamanan

Untuk masalah keamanan, silakan hubungi security@hashicorp.com atau ikuti kebijakan keamanan kami.

Dukungan

Untuk laporan bug dan permintaan fitur, silakan buka issue di GitHub.

Untuk pertanyaan umum dan diskusi, buka Diskusi GitHub.