Terraform MCP Sunucusu

Terraform MCP Sunucusu, Model Context Protocol (MCP) sunucusu olup Terraform Registry API'leriyle sorunsuz entegrasyon sağlayarak, Altyapı Kod Olarak (IaC) geliştirme için gelişmiş otomasyon ve etkileşim yetenekleri sunar.

Özellikler

• Çift Transport Desteği: Stdio ve StreamableHTTP transportları yapılandırılabilir uç noktalarla
• Terraform Registry Entegrasyonu: Sağlayıcılar, modüller ve politikalar için genel Terraform Registry API'leriyle doğrudan entegrasyon
• HCP Terraform & Terraform Enterprise Desteği: Tam workspace yönetimi, organizasyon/proje listeleme ve özel registry erişimi
• Workspace İşlemleri: Değişkenler, etiketler ve run yönetimine destek ile workspace'ler oluşturun, güncelleyin, silin
• OTel metrikleri araç kullanımını izlemek için: Açık telemetri meterleriyle entegrasyon, StreamableHTTP modunda araç çağrı hacmini, gecikmeyi ve başarısızlıkları izler. Bu özellik etkinleştirildiğinde varsayılan http sunucusu metriklerini de sunar

Güvenlik Notu: Bu aşamada MCP sunucusu yalnızca yerel kullanım için tasarlanmıştır. StreamableHTTP transportunu kullanıyorsanız, erişimi yalnızca güvenilen kaynaklar ile sınırlamak için her zaman MCP_ALLOWED_ORIGINS ortam değişkenini yapılandırın. Bu, DNS rebinding saldırılarını ve diğer cross-origin açıklarını önlemeye yardımcı olur.

Güvenlik Notu: Sorguya bağlı olarak MCP sunucusu belirli Terraform verilerini MCP istemcisine ve LLM'ye maruz bırakabilir. MCP sunucusunu güvenilmeyen MCP istemcileri veya LLM'ler ile kullanmayın.

Yasal Notu: Üçüncü taraf MCP İstemcisi/LLM kullanımınız yalnızca söz konusu MCP/LLM'nin kullanım şartlarına tabidir ve IBM, bu tür üçüncü taraf araçların performansından sorumlu değildir. IBM, üçüncü taraf MCP İstemcileri/LLM'ler için tüm garantileri ve sorumluluğu açıkça reddetmektedir ve bu tür üçüncü taraf araçlar tarafından neden olunan sorunları çözmek için destek sağlayamayabilir.

Dikkat: MCP sunucusu tarafından sağlanan çıktılar ve öneriler dinamik olarak oluşturulur ve sorguya, modele ve bağlı MCP istemcisine göre değişebilir. Kullanıcılar, uygulamadan önce tüm çıktıları/önerileri kuruluşlarının güvenlik en iyi uygulamaları, maliyet verimlilik hedefleri ve uyum gereksinimleriyle uyumlu olduğundan emin olmak için kapsamlı bir şekilde gözden geçirmelidir.

Ön Koşullar

1. Sunucuyu konteynerleştirilmiş ortamda kullanmak için Docker'ın kurulu ve çalışır durumda olduğundan emin olun.
2. Model Context Protocol (MCP)'yi destekleyen bir yapay zeka asistanı yükleyin.

Komut Satırı Seçenekleri

Ortam Değişkenleri:

# Stdio modu
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP modu
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

Talimatlar

MCP sunucusunun varsayılan talimatları cmd/terraform-mcp-server/instructions.md dosyasında yer almaktadır; bu talimatlar kuruluşunuzun Terraform uygulamaları için uygun görünmüyorsa veya MCP sunucusu yanlış yanıtlar üretiyorsa, lütfen bunları kendi talimatlarınızla değiştirin ve container'ı veya binary'yi yeniden derleyin. Böyle bir talimat örneği instructions/example-mcp-instructions.md konumunda yer almaktadır.

AGENTS.md temelde kodlama ajanları için README'ler gibi davranır: yapay zeka kodlama ajanlarının projeniz üzerinde çalışmasına yardımcı olmak için bağlam ve talimatlar sağlamaya yönelik adanmış, öngörülebilir bir yer. Bir AGENTS.md dosyası farklı kodlama ajanlarıyla çalışır. Böyle bir talimat örneği instructions/example-AGENTS.md konumunda yer almaktadır; bunu kullanmak için Terraform yapılandırmalarınızın bulunduğu dizine AGENTS.md adında bir dosya commit'leyin.

Kurulum

Visual Studio Code ile Kullanım

Aşağıdaki JSON bloğunu VS Code'daki Kullanıcı Ayarları (JSON) dosyasına ekleyin. Bunu Ctrl + Shift + P tuşlarına basıp Preferences: Open User Settings (JSON) yazarak yapabilirsiniz.

VS Code'un agent modu dokümantasyonunda MCP sunucusu araçlarını kullanma hakkında daha fazla bilgi.

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

İsteğe bağlı olarak, çalışma alanınızda .vscode/mcp.json adlı bir dosyaya benzer bir örnek (yani mcp anahtarı olmadan) ekleyebilirsiniz. Bu, konfigürasyonu diğerleriyle paylaşmanıza izin verecektir.

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_TOKEN=${input:tfe_token}",
        "-e", "TFE_ADDRESS=${input:tfe_address}",
        "hashicorp/terraform-mcp-server:0.5.2"
      ]
    }
  },
  "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"
      ]
    }
  }
}

Cursor ile Kullanım

Bunu Cursor konfigürasyonunuza (~/.cursor/mcp.json) veya Ayarlar → Cursor Ayarları → MCP üzerinden ekleyin:

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

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

Claude Desktop / Amazon Q Developer / Kiro CLI ile Kullanım

Claude Desktop'ta MCP sunucusu araçlarını kullanma hakkında daha fazla bilgi için kullanıcı dokümantasyonuna bakın. Amazon Q Developer ve Kiro CLI'de MCP sunucusu kullanma hakkında daha fazla bilgi edinin.

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

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

Claude Code ile Kullanım

Claude Code'da MCP sunucusu araçlarını kullanma ve ekleme hakkında daha fazla bilgi için kullanıcı dokümantasyonuna bakın.

• Yerel (stdio) Transport

claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

• Uzak (streamable-http) Transport

# Sunucuyu çalıştır (örnek)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Claude Code'a ekle
claude mcp add --transport http terraform http://localhost:8080/mcp

Gemini uzantıları ile Kullanım

Güvenlik için, kimlik bilgilerinizi hardcode etmeyin; HCP Terraform veya Terraform Enterprise kimlik bilgilerini depolamak için ~/.gemini/.env oluşturun veya güncelleyin (burada ~ ev veya proje dizininizdir)

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

Uzantıyı yükleyin ve Gemini'yi çalıştırın

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

Bob IDE / Shell ile Kullanım

Bob IDE veya Shell'de MCP sunucusu araçlarını kullanma ve ekleme hakkında daha fazla bilgi için Bob'da MCP Kullanımı bölümüne bakın.

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

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

Kaynaktan Yükleme

En son release sürümünü kullanın:

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

main branch'ini kullanın:

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

Docker İmajını Yerel Olarak Derleme

Sunucuyu kullanmadan önce Docker imajını yerel olarak derlemeniz gerekir:

1. Depoyu klonlayın:

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

2. Docker imajını derleyin:

make docker-build

3. Bu, aşağıdaki konfigürasyonda kullanabileceğiniz yerel bir Docker imajı oluşturacaktır.

# Stdio modunda çalıştır
docker run -i --rm terraform-mcp-server:dev

# streamable-http modunda çalıştır
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# Araçları filtrele (isteğe bağlı)
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

Not: Docker'da çalıştırırken, container'ın dışından bağlantılara izin vermek için TRANSPORT_HOST=0.0.0.0 ayarlamalısınız.

4. (İsteğe bağlı) Http modunda bağlantıyı test edin

# Bağlantıyı test et
curl http://localhost:8080/health

5. Bunu yapay zeka asistanınızda aşağıdaki gibi kullanabilirsiniz:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Mevcut Araçlar

Mevcut araçları burada kontrol edin :link:

Mevcut Kaynaklar

Mevcut kaynakları burada kontrol edin :link:

Mevcut Metrikler

İki tür metrik toplanmaktadır. İlk olarak, HTTP mux'u otelhttp.NewHandler(...) ile kaplayarak standart HTTP sunucusu metrikleri eklenir. Bu, aşağıdakileri yayarlar:

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

İkincisi, MCP sunucusu MCP hooks'ları (BeforeCallTool / AfterCallTool) kullanarak araç yürütme etrafında özel araç metrikleri kaydeder. Bunlar aşağıdakileri yayarlar:

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

Araç Filtreleme

--toolsets (gruplar) veya --tools (bireysel) kullanarak hangi araçların kullanılabilir olduğunu kontrol edin:

# Araç gruplarını etkinleştir (varsayılan: registry)
terraform-mcp-server --toolsets=registry,terraform

# Yalnızca belirli araçları etkinleştir
terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces

Mevcut araç setleri: registry, registry-private, terraform, all, default. Bireysel araç adları için pkg/toolsets/mapping.go dosyasına bakın. Her iki bayrağı birlikte kullanamaz.

Transport Desteği

Terraform MCP Sunucusu birden fazla transport protokolünü destekler:

1. Stdio Transport (Varsayılan)

JSON-RPC mesajlarını kullanarak standart giriş/çıkış iletişimi. Yerel geliştirme ve MCP istemcileriyle doğrudan entegrasyon için idealdir.

2. StreamableHTTP Transport

Hem doğrudan HTTP isteklerini hem de Sunucu Tarafından Gönderilen Olayları (SSE) akışlarını destekleyen modern HTTP tabanlı transport. Bu, uzak/dağıtılmış kurulumlar için önerilen transporttur.

Özellikler:

• Uç Nokta: http://{hostname}:8080/mcp
• Sağlık Kontrolü: http://{hostname}:8080/health
• Ortam Konfigürasyonu: HTTP transportunu etkinleştirmek için TRANSPORT_MODE=http veya TRANSPORT_PORT=8080 ayarlayın

Oturum Modları

Terraform MCP Sunucusu, StreamableHTTP transportu kullanılırken iki oturum modunu destekler:

• Stateful Modu (Varsayılan): İstekler arasında oturum durumunu koruyarak bağlam duyarlı işlemleri sağlar.
• Stateless Modu: Her istek, oturum durumunu korumadan bağımsız olarak işlenir; bu, yüksek kullanılabilirlik dağıtımları veya yük dengeleyicileri kullanırken kullanışlı olabilir.

Stateless modunu etkinleştirmek için ortam değişkenini ayarlayın:

export MCP_SESSION_MODE=stateless

Sorun Giderme

Kurumsal Proxy / TLS Denetimi (Zscaler, vb.)

Kurumsal TLS denetimi yapan bir proxy'nin arkasındaysanız (Zscaler Internet Access gibi), sertifika hataları görebilirsiniz:

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

Çözüm: Kurumsal CA sertifikanızı container'a bağlayın:

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:0.5.2

MCP istemci konfigürasyonları için:

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

Alternatif: Binary'yi doğrudan çalıştırın

Docker'ın ortamınızda izin verilmemesi