Terraform MCP Server

Terraform MCP Server

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

Fitur

• Dukungan Transport Ganda: Transport Stdio dan StreamableHTTP dengan endpoint yang dapat dikonfigurasi
• Integrasi Terraform Registry: Integrasi langsung dengan API Terraform Registry publik untuk penyedia, modul, dan kebijakan
• Dukungan HCP Terraform & Terraform Enterprise: Manajemen ruang kerja penuh, daftar organisasi/proyek, dan akses registri privat
• Operasi Ruang Kerja: Membuat, memperbarui, menghapus ruang kerja dengan dukungan untuk variabel, tag, dan manajemen run
• Metrik OTel untuk memantau penggunaan alat: Integrasi dengan meter telemetri terbuka untuk melacak volume panggilan alat, latensi, dan kegagalan dalam mode HTTP Streamable. 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 terhadap Klien MCP/LLM pihak ketiga sepenuhnya tunduk pada ketentuan penggunaan untuk MCP/LLM tersebut, dan IBM tidak bertanggung jawab atas kinerja alat pihak ketiga tersebut. IBM secara tegas menyangkal semua jaminan dan tanggung jawab untuk Klien MCP/LLM pihak ketiga, dan mungkin tidak dapat memberikan dukungan untuk menyelesaikan masalah yang disebabkan oleh alat pihak ketiga.

Perhatian: Keluaran 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 keluaran/rekomendasi untuk memastikan kesesuaiannya dengan praktik terbaik keamanan, tujuan efisiensi biaya, dan persyaratan kepatuhan organisasi mereka sebelum implementasi.

Prasyarat

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

Opsi Baris Perintah

Variabel Lingkungan:

# 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 tampaknya tidak sesuai untuk praktik Terraform organisasi Anda atau jika server MCP menghasilkan respons yang tidak akurat, harap 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 sebagai README untuk agen pengkodean: tempat khusus yang dapat diprediksi untuk menyediakan konteks dan instruksi guna membantu agen pengkodean AI mengerjakan proyek Anda. Satu file AGENTS.md berfungsi dengan agen pengkodean yang berbeda. Contoh instruksi tersebut terletak di instructions/example-AGENTS.md, untuk menggunakannya, komit file bernama AGENTS.md ke direktori tempat konfigurasi Terraform Anda berada.

Instalasi

Penggunaan dengan Visual Studio Code

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

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

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

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

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

Penggunaan dengan Cursor

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

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.1.0"
      ]
    }
  }
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Penggunaan dengan Claude Desktop / Amazon Q Developer / Kiro CLI

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

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

Penggunaan dengan Claude Code

Lebih lanjut tentang menggunakan dan menambahkan alat server MCP di dokumentasi pengguna Claude Code

• 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 ekstensi Gemini

Untuk keamanan, hindari hardcode kredensial Anda, buat atau perbarui ~/.gemini/.env (di mana ~ adalah direktori home 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

Lebih lanjut tentang menggunakan dan menambahkan alat server MCP di Bob IDE atau Shell Menggunakan MCP di Bob.

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

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

{
  "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 Docker Image secara lokal

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

1. Kloning repositori:

git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server

2. Bangun Docker image:

make docker-build

3. Ini akan membuat Docker image 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 berjalan di Docker, Anda harus mengatur TRANSPORT_HOST=0.0.0.0 untuk mengizinkan koneksi dari luar kontainer.

4. (Opsional) Uji koneksi dalam mode http

# Test the connection
curl http://localhost:8080/health

5. Anda dapat menggunakannya di 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 HTTP mux 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 seputar 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

Alat yang tersedia: registry, registry-private, terraform, all, default. Lihat pkg/toolsets/mapping.go untuk nama alat individual. Tidak dapat menggunakan kedua flag 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 mengirimkan token Terraform mereka sendiri melalui header HTTP untuk penegakan RBAC. Ini memungkinkan satu instance server melayani banyak pengguna dengan izin yang berbeda.

Ketika 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 bearer diutamakan 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 menghasilkan 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 dinonaktifkan secara default dan harus diaktifkan dengan MCP_FORWARD_CLIENT_IP=true.

Saat diaktifkan, server mengambil IP klien sesuai dengan MCP_REMOTE_IP_METHOD:

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 peer yang terhubung langsung dengan server. Hanya aktifkan X-Real-IP atau X-Forwarded-For ketika 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 dari mana ia menerima permintaan dan entri paling kanan diatur oleh proxy yang paling dekat dengan server. Server melewatkan sejumlah entri tepercaya tersebut dan mengambil yang berikutnya di sebelah 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 fallback ke RemoteAddr.

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

Keterbatasan

• Server hanya membaca header X-Forwarded-For pertama pada permintaan. Valid bagi permintaan untuk membawa beberapa header X-Forwarded-For, tetapi pustaka standar Go hanya mengembalikan yang pertama, dan server tidak menggabungkannya. Jika rantai proxy Anda menghasilkan beberapa header, konfigurasikan untuk menghasilkan satu header X-Forwarded-For gabungan.
• Alamat IPv4 dan IPv6 keduanya didukung. Nilai yang bukan IP valid ditolak dan server fallback 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 adalah yang paling mudah dipalsukan. Defaultnya sekarang adalah RemoteAddr. Jika Anda menjalankan server di belakang proxy dan mengandalkan X-Forwarded-For 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

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 bersumber dari variabel lingkungan sisi server TFE_ADDRESS (atau default). Permintaan yang mencoba mengatur TFE_ADDRESS melalui header HTTP atau parameter kueri ditolak dengan 403. Ini mencegah klien mengalihkan permintaan, dan token Authorization, ke server jahat.
• Jangan pernah mengirimkan 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 dalam perjalanan.
• 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.1.0

Pengguna kemudian terhubung dengan token individual 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.1.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.1.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 build kontainer)

Perintah Make yang Tersedia

Berkontribusi

1. Fork repositori
2. Buat cabang fitur Anda
3. Lakukan perubahan Anda
4. Jalankan pengujian
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 isu di GitHub.

Untuk pertanyaan umum dan diskusi, buka Diskusi GitHub.