Terraform MCP Server

resmi

HashiCorp Terraform MCP sunucusu, Terraform Registry üzerinden sağlayıcı ve modül keşfi dahil olmak üzere Altyapı Olarak Kod iş akışları için kullanılır.

Terraform MCP ile neler yapabilirsiniz?

  • Genel Terraform Registry'de arama yapın — AI'den search_providers veya search_modules kullanarak anahtar kelimeyle sağlayıcı veya modül bulmasını isteyin.
  • Sağlayıcı ve modül ayrıntılarını alın — belirli bir sağlayıcı veya modül için dokümantasyon, sürümler ve girdi/çıktıları get_provider_details ve get_module_details aracılığıyla alın.
  • HCP Terraform çalışma alanlarını yönetin — çalışma alanlarını listeleyin, oluşturun, güncelleyin veya silin ve değişkenlerini, etiketlerini ve çalıştırmalarını list_workspaces, create_workspace ve ilgili araçlarla yönetin.
  • Kuruluşları ve projeleri listeleyin — erişilebilir HCP Terraform kuruluşlarını ve projelerini list_organizations ve list_projects kullanarak göz atın.
  • Özel kayıt defterlerine erişin — bir TFE örneğine bağlandığınızda özel Terraform Enterprise kayıt defterlerinden arama yapın ve ayrıntıları alın.

Dokümantasyon

Terraform MCP Sunucusu

Terraform MCP Sunucusu, Kod Olarak Altyapı (IaC) geliştirme için gelişmiş otomasyon ve etkileşim yetenekleri sağlayan, Terraform Registry API'leri ile sorunsuz entegrasyon sunan bir Model Bağlam Protokolü (MCP) sunucusudur.

Özellikler

  • Çift Taşıma Desteği: Yapılandırılabilir uç noktalarla hem Stdio hem de StreamableHTTP taşımaları
  • Terraform Registry Entegrasyonu: Sağlayıcılar, modüller ve politikalar için genel Terraform Registry API'leri ile doğrudan entegrasyon
  • HCP Terraform & Terraform Enterprise Desteği: Tam çalışma alanı yönetimi, organizasyon/proje listeleme ve özel kayıt defteri erişimi
  • Çalışma Alanı İşlemleri: Değişkenler, etiketler ve çalıştırma yönetimi desteğiyle çalışma alanları oluşturma, güncelleme, silme
  • Araç kullanımını izlemek için OTel metrikleri: Streamable HTTP modunda araç çağrı hacmini, gecikmeyi ve hataları izlemek için açık telemetri ölçerlerle entegrasyon. Bu özellik etkinleştirildiğinde varsayılan http sunucu metriklerini de sunar

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

Yasal Not: Üçüncü taraf bir MCP İstemcisi/LLM kullanımınız yalnızca ilgili MCP/LLM'nin kullanım koşullarına tabidir ve IBM bu üçü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 reddeder ve üçüncü taraf araçlardan kaynaklanan 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 bağlı olarak değişiklik gösterebilir. Kullanıcılar, uygulamadan önce tüm çıktıların/önerilerin kuruluşlarının güvenlik en iyi uygulamaları, maliyet verimliliği hedefleri ve uyumluluk gereksinimleriyle uyumlu olduğundan emin olmak için kapsamlı bir şekilde incelemelidir.

Ön Koşullar

  1. Sunucuyu konteynerli bir ortamda kullanmak için Docker'ın kurulu ve çalışır durumda olduğundan emin olun.
  2. Model Bağlam Protokolü'nü (MCP) destekleyen bir AI asistanı kurun.

Komut Satırı Seçenekleri

Ortam Değişkenleri:

DeğişkenAçıklamaVarsayılan
TFE_ADDRESSAPI çağrıları için Terraform Enterprise/HCP Terraform adresini ayarlar. Protokolü içermelidir (örn., https://app.terraform.io). Streamable-http modunda adresi ayarlamanın tek yolu budur; istemciler tarafından başlık veya sorgu parametresi ile sağlanamaz.İsteğe bağlı
TFE_TOKENTerraform Enterprise API belirteci"" (boş)
TF_MCP_SHARED_SECRETBarındırılan bir MCP dağıtımından kaynaklanan istekleri tanımlamak için kullanılan, HCP Terraform / TFE'ye yapılan isteklerde X-Tf-Mcp-Secret başlığı olarak gönderilen paylaşılan sır. Yalnızca TLS üzerinden kullanılmalıdır."" (boş)
TFE_SKIP_TLS_VERIFYHCP Terraform veya Terraform Enterprise TLS doğrulamasını atlafalse
LOG_LEVELGünlük seviyesi: trace, debug, info, warn, error, fatal, panic (--log-level bayrağını geçersiz kılar)info
LOG_FORMATGünlük formatı: text veya json (--log-format bayrağını geçersiz kılar)text
TRANSPORT_MODEHTTP taşımasını etkinleştirmek için streamable-http olarak ayarlayın (eski http değeri hala desteklenir)stdio
TRANSPORT_HOSTHTTP sunucusunun bağlanacağı ana bilgisayar127.0.0.1
TRANSPORT_PORTHTTP sunucu portu8080
MCP_ENDPOINTHTTP sunucu uç nokta yolu/mcp
MCP_REDIRECT_ROOT_URLİstekleri / adresine yönlendirmek için URL""
MCP_KEEP_ALIVESSE bağlantıları için keep-alive aralığı (örn., 30s, 1m). Devre dışı bırakmak için 00
MCP_SESSION_MODEOturum modu: stateful veya statelessstateful
MCP_ALLOWED_ORIGINSCORS için izin verilen kaynakların virgülle ayrılmış listesi"" (boş)
MCP_CORS_MODECORS modu: strict, development veya disabledstrict
MCP_TLS_CERT_FILETLS sertifika dosyasının yolu, localhost dışı dağıtım için gereklidir (örn. /path/to/cert.pem)"" (boş)
MCP_TLS_KEY_FILETLS anahtar dosyasının yolu, localhost dışı dağıtım için gereklidir (örn. /path/to/key.pem)"" (boş)
MCP_RATE_LIMIT_GLOBALGenel hız sınırı (format: rps:burst)10:20
MCP_RATE_LIMIT_SESSIONOturum başına hız sınırı (format: rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTHTTP sunucusuna erişmesine izin verilen HCP Terraform organizasyon adlarının CSV listesi"" (boş)
MCP_FORWARD_CLIENT_IPX-Forwarded-For aracılığıyla istemci IP'sini HCP Terraform / TFE'ye ilet. Etkinleştirmek için true olarak ayarlayınfalse
MCP_REMOTE_IP_METHODİletme etkinleştirildiğinde istemci IP'sinin nasıl alınacağı: RemoteAddr (yalnızca doğrudan bağlantı), X-Real-IP veya X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSX-Forwarded-For zincirinin sağından sayılan güvenilen proxy atlama sayısı. Yalnızca MCP_REMOTE_IP_METHOD=X-Forwarded-For olduğunda kullanılır0
ENABLE_TF_OPERATIONSAçık onay gerektiren araçları etkinleştirfalse
OTEL_METRICS_ENABLEDOtel kullanarak araç ve sunucu metriklerini etkinleştirfalse
OTEL_METRICS_SERVICE_VERSIONMetrik özniteliklerini ayarlamak için kullanılan, metrik gönderen terraform-mcp-server sürümü. Ayrıca farklı dağıtımlar arasında metriklerin izlenmesine yardımcı olurlatest
OTEL_METRICS_SERVICE_NAMEMetriklerin kaynağını tanımlar (örn., "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALMetrik temizleme sıklığını kontrol eder2
OTEL_METRICS_ENDPOINTOTel Toplayıcınızın veya arka ucunuzun URL'silocalhost:4318
INSTANA_ENABLEDStreamable-http sunucusu için Instana enstrümantasyonunu (metrikler ve HTTP istek izleme) etkinleştir. Sunucu tarafından erişilebilir bir Instana ajanı gerektirir.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>]

Talimatlar

MCP sunucusu için varsayılan talimatlar cmd/terraform-mcp-server/instructions.md konumunda bulunur, eğer bunlar kuruluşunuzun Terraform uygulamaları için uygun görünmüyorsa veya MCP sunucusu hatalı yanıtlar üretiyorsa, lütfen bunları kendi talimatlarınızla değiştirin ve konteyneri veya ikili dosyayı yeniden oluşturun. Bu tür bir talimat örneği instructions/example-mcp-instructions.md konumunda bulunur

AGENTS.md, kodlama ajanları için esasen BENİOKU dosyaları gibi davranır: AI kodlama ajanlarının projeniz üzerinde çalışmasına yardımcı olmak için bağlam ve talimatlar sağlamak üzere özel, öngörülebilir bir yer. Bir AGENTS.md dosyası farklı kodlama ajanlarıyla çalışır. Bu tür bir talimat örneği instructions/example-AGENTS.md konumunda bulunur, kullanmak için Terraform yapılandırmalarınızın bulunduğu dizine AGENTS.md adında bir dosya ekleyin.

Kurulum

Visual Studio Code ile Kullanım

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

VS Code'un ajan modu belgelerinde MCP sunucu araçlarını kullanma hakkında daha fazla bilgi.

Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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"
        ]
      }
    }
  }
}

İ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, yapılandırmayı başkalarıyla paylaşmanıza olanak tanır.

Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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)

Cursor ile Kullanım

Bunu Cursor yapılandırmanıza (~/.cursor/mcp.json) veya Ayarlar → Cursor Ayarları → MCP aracılığıyla ekleyin:

Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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

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

Claude Desktop kullanıcı belgelerinde MCP sunucu araçlarını kullanma hakkında daha fazla bilgi. Amazon Q Developer ve Kiro CLI'da MCP sunucusu kullanma hakkında daha fazlasını okuyun.

Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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"
      ]
    }
  }
}

Claude Code ile Kullanım

Claude Code kullanıcı belgelerinde MCP sunucu araçlarını kullanma ve ekleme hakkında daha fazla bilgi

  • Yerel (stdio) Taşıma
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Uzak (streamable-http) Taşıma
# 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

Gemini uzantıları ile Kullanım

Güvenlik için, kimlik bilgilerinizi sabit kodlamaktan kaçının, HCP Terraform veya Terraform Enterprise kimlik bilgilerini saklamak için ~/.gemini/.env dosyasını 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ı kurun 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 sunucu araçlarını kullanma ve ekleme hakkında daha fazla bilgi Bob'da MCP Kullanımı.

Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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
    }
  }
}

Kaynaktan Kurulum

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

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

Ana dalı kullanın:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Sürüm 0.3.0+ veya üstüSürüm 0.2.3 veya altı
{
  "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 Oluşturma

Sunucuyu kullanmadan önce, Docker imajını yerel olarak oluşturmanız gerekir:

  1. Depoyu klonlayın:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Docker imajını oluşturun:
make docker-build
  1. Bu, aşağıdaki yapılandırmada kullanabileceğiniz yerel bir Docker imajı oluşturacaktır.
# 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

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

  1. (İsteğe bağlı) Http modunda bağlantıyı test edin
# Test the connection
curl http://localhost:8080/health
  1. AI 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ı buradan kontrol edin :link:

Mevcut Kaynaklar

Mevcut kaynakları buradan kontrol edin :link:

Mevcut Metrikler

İki tür metrik toplanır. İlk olarak, HTTP mux'u otelhttp.NewHandler(...) ile sararak standart HTTP sunucu metrikleri eklenir. Bu şunları yayar:

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

İkinci olarak, MCP sunucusu, MCP kancalarını (BeforeCallTool / AfterCallTool) kullanarak araç yürütme etrafında özel araç metrikleri kaydeder. Bunlar şunları yayar:

  1. mcp_tool_calls_total
  2. mcp_tool_errors_total
  3. mcp_tool_duration_seconds

Araç Filtreleme

Hangi araçların kullanılabileceğini --toolsets (gruplar) veya --tools (tek tek) ile kontrol edin:

# 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

Kullanılabilir araç setleri: registry, registry-private, terraform, all, default. Tekil araç adları için pkg/toolsets/mapping.go bölümüne bakın. Her iki bayrak birlikte kullanılamaz.

Aktarım Desteği

Terraform MCP Sunucusu birden fazla aktarım protokolünü destekler:

1. Stdio Aktarımı (Varsayılan)

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

2. StreamableHTTP Aktarımı

Hem doğrudan HTTP isteklerini hem de Sunucu Tarafından Gönderilen Olay (SSE) akışlarını destekleyen modern HTTP tabanlı aktarım. Uzak/dağıtık kurulumlar için önerilen aktarım yöntemidir.

Özellikler:

  • Uç Nokta: http://{hostname}:8080/mcp
  • Sağlık Kontrolü: http://{hostname}:8080/health
  • Ortam Yapılandırması: Etkinleştirmek için TRANSPORT_MODE=http veya TRANSPORT_PORT=8080 ayarlayın
  • Organizasyon İzin Listesi: İzin verilen HCP Terraform organizasyon adlarının CSV listesi için MCP_ORGANIZATION_ALLOWLIST veya --organization-allowlist ayarlayın

Oturum Modları

Terraform MCP Sunucusu, StreamableHTTP aktarımını kullanırken iki oturum modunu destekler:

  • Durum Bilgili Mod (Varsayılan): İstekler arasında oturum durumunu koruyarak bağlama duyarlı işlemlere olanak tanır.
  • Durum Bilgisiz Mod: Her istek, oturum durumu korunmadan bağımsız olarak işlenir; bu, yüksek erişilebilirlik dağıtımları veya yük dengeleyiciler kullanırken faydalı olabilir.

Durum bilgisiz modu etkinleştirmek için ortam değişkenini ayarlayın:

export MCP_SESSION_MODE=stateless

Merkezi Dağıtımlar için Token Aktarımı

MCP sunucusu birden fazla kullanıcı için merkezi olarak (StreamableHTTP modunda) çalıştırıldığında, her kullanıcı RBAC uygulaması için HTTP başlıkları aracılığıyla kendi Terraform token'ını iletebilir. Bu, tek bir sunucu örneğinin farklı izinlere sahip birden fazla kullanıcıya hizmet vermesini sağlar.

MCP_ORGANIZATION_ALLOWLIST veya --organization-allowlist yapılandırıldığında, izin listesi HCP Terraform organizasyon adlarının CSV listesi olmalıdır. Sunucu Authorization: Bearer <token> gerektirir ve bu token CSV izin listesindeki en az bir organizasyona erişemediği sürece istekleri reddeder. İstek ayrıca bir TFE_TOKEN başlığı içeriyorsa taşıyıcı token önceliklidir, böylece izin listesi tarafından doğrulanan token'ın Terraform API istekleri için kullanılan token olması sağlanır. Organizasyon adı eşleştirmesi büyük/küçük harf duyarsızdır. Yapılandırılan CSV değeri sıfır organizasyon adına çözümlenirse, sunucu hatalı biçimlendirilmiş organizasyon izin listesi hatasıyla çıkar.

İstemci IP Yönlendirme

MCP sunucusu bir proxy veya yük dengeleyici arkasında merkezi olarak çalıştırıldığında, X-Forwarded-For başlığı aracılığıyla kaynak istemcinin IP'sini HCP Terraform / TFE'ye iletebilirsiniz. Bu varsayılan olarak kapalıdır ve MCP_FORWARD_CLIENT_IP=true ile etkinleştirilmelidir.

Etkinleştirildiğinde, sunucu istemci IP'sini MCP_REMOTE_IP_METHOD uyarınca alır:

YöntemDavranış
RemoteAddr (varsayılan)Yalnızca doğrudan TCP bağlantısının adresini kullanır. X-Forwarded-For ve X-Real-IP yok sayar.
X-Real-IPGeçerli bir IP ise X-Real-IP başlığını kullanır, aksi takdirde RemoteAddr geri döner.
X-Forwarded-ForX-Forwarded-For zincirini kullanır, sağdan MCP_XFF_TRUSTED_HOPS konumundaki girişi seçer. Değer eksik veya geçersizse RemoteAddr geri döner.

Güven modeli

X-Forwarded-For ve X-Real-IP istemciler ve aracı proxy'ler tarafından ayarlanır, bu nedenle sunucunun önündeki güvenilir bir proxy bunların üzerine yazmadığı sürece taklit edilebilirler. Bu nedenle varsayılan RemoteAddr olup, yalnızca sunucunun doğrudan bağlı olduğu eşe güvenir. X-Real-IP veya X-Forwarded-For yalnızca sunucu, bu başlıkları ayarlayan kontrolünüzdeki bir proxy'nin arkasında olduğunda etkinleştirin.

Güvenilir atlama sayısı

X-Forwarded-For kullanırken, MCP_XFF_TRUSTED_HOPS sunucu ile internet arasında işlettiğiniz proxy sayısıdır. Atlama sayısı zincirin sağından sayılır, çünkü her proxy isteği aldığı adresi ekler ve en sağdaki giriş sunucuya en yakın proxy tarafından ayarlanır. Sunucu bu kadar güvenilir girişi atlar ve bir sonrakini soldan alır.

Örneğin, MCP_XFF_TRUSTED_HOPS=1 ve 200.1.2.3, 10.1.1.10 başlığı ile sunucu 200.1.2.3 seçer. MCP_XFF_TRUSTED_HOPS=2 ve 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1 ile 200.1.2.3 seçer. Atlama sayısı giriş sayısından fazlaysa veya seçilen giriş geçerli bir IP değilse, sunucu RemoteAddr geri döner.

Atlama sayısını çok düşük ayarlamak istemci tarafından sağlanan bir değere güvenir; çok yüksek ayarlamak kendi altyapınızdaki daha içerideki bir adrese güvenir. Tam olarak işlettiğiniz proxy sayısına ayarlayın.

Sınırlamalar

  • Sunucu bir istekte yalnızca ilk X-Forwarded-For başlığını okur. Bir isteğin birden fazla X-Forwarded-For başlığı taşıması geçerlidir, ancak Go'nun standart kütüphanesi yalnızca ilkini döndürür ve sunucu bunları birleştirmez. Proxy zinciriniz birden fazla başlık yayıyorsa, tek bir birleşik X-Forwarded-For başlığı yayacak şekilde yapılandırın.
  • Hem IPv4 hem de IPv6 adresleri desteklenir. Geçerli IP olmayan değerler reddedilir ve sunucu RemoteAddr geri döner.

Önceki sürümlerden geçiş

Önceki sürümler, başlık mevcut olduğunda en soldaki X-Forwarded-For değerini hiçbir yapılandırma olmadan kullanıyordu. En soldaki değer en kolay taklit edilebilen olduğu için bu güvensizdi. Varsayılan artık RemoteAddr. Sunucuyu bir proxy arkasında çalıştırıyor ve X-Forwarded-For HCP Terraform / TFE'ye iletilmesine güveniyorsanız, MCP_REMOTE_IP_METHOD=X-Forwarded-For ve MCP_XFF_TRUSTED_HOPS işlettiğiniz proxy sayısına ayarlayın.

Desteklenen Başlıklar

BaşlıkAçıklama
TFE_TOKENTerraform API token'ı
Authorization: Bearer <token>Standart Bearer kimlik doğrulaması kullanan alternatif yöntem
TFE_SKIP_TLS_VERIFYİstek için TLS doğrulamasını atla

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

Güvenlik Hususları

  • TFE_ADDRESS istemciler tarafından ayarlanamaz. Streamable-http modunda Terraform adresi yalnızca sunucu tarafındaki TFE_ADDRESS ortam değişkeninden (veya varsayılandan) alınır. HTTP başlığı veya sorgu parametresi aracılığıyla TFE_ADDRESS ayarlamaya çalışan istekler 403 ile reddedilir. Bu, bir istemcinin istekleri ve Authorization token'ını kötü niyetli bir sunucuya yönlendirmesini engeller.
  • Barındırılan dağıtım tanımlaması: TF_MCP_SHARED_SECRET ayarlamak, bu değeri her HCP Terraform / TFE isteğinde X-Tf-Mcp-Secret başlığı olarak gönderir ve arka ucun bilinen bir barındırılan dağıtımdan gelen istekleri tanımlamasını sağlar (ör. IP izin listeleri uygulamak için). Bir başlıkta gönderilen statik bir gizli anahtardır, bu nedenle yalnızca TLS üzerinden kullanın ve değeri bir kimlik bilgisi olarak değerlendirin.
  • Token'ları asla sorgu parametrelerinde iletmeyin - sunucu bu tür istekleri 400 hatasıyla reddeder.
  • Token'ları aktarım sırasında korumak için merkezi dağıtım yaparken her zaman TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) kullanın.
  • Hangi istemcilerin bağlanabileceğini kısıtlamak için MCP_ALLOWED_ORIGINS yapılandırın.

Merkezi Dağıtım Örneği

# 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

Kullanıcılar daha sonra başlıklar aracılığıyla iletilen kendi bireysel token'ları ile bağlanır ve kullanıcı başına RBAC uygulaması etkinleştirilir.

Sorun Giderme

Kurumsal Proxy / TLS Denetimi (Zscaler, vb.)

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

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

Çözüm: Kurumsal CA sertifikanızı konteynere 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:1.1.0

MCP istemci yapılandırmaları 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:1.1.0"
      ]
    }
  }
}

Alternatif: İkili dosyayı doğrudan çalıştırın

Ortamınızda Docker'a izin verilmiyorsa, sisteminizin sertifika deposunu kullanacak olan sunucu ikili dosyasını doğrudan yükleyip çalıştırabilirsiniz:

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

Geliştirme

Ön Koşullar

  • Go (belirli sürüm için go.mod dosyasına bakın)
  • Docker (isteğe bağlı, konteyner yapıları için)

Kullanılabilir Make Komutları

KomutAçıklama
make buildİkili dosyayı oluştur
make testTüm testleri çalıştır
make test-e2eUçtan uca testleri çalıştır
make docker-buildDocker imajı oluştur
make run-httpHTTP sunucusunu yerel olarak çalıştır
make docker-run-httpHTTP sunucusunu Docker'da çalıştır
make test-httpHTTP sağlık uç noktasını test et
make cleanDerleme kalıntılarını kaldır
make helpTüm kullanılabilir komutları göster

Katkıda Bulunma

  1. Depoyu çatallayın
  2. Özellik dalınızı oluşturun
  3. Değişikliklerinizi yapın
  4. Testleri çalıştırın
  5. Bir çekme isteği gönderin

Lisans

Bu proje MPL-2.0 açık kaynak lisansı koşulları altında lisanslanmıştır. Tam koşullar için lütfen LICENSE dosyasına bakın.

Güvenlik

Güvenlik sorunları için lütfen security@hashicorp.com adresine e-posta gönderin veya güvenlik politikamızı izleyin.

Destek

Hata raporları ve özellik istekleri için lütfen GitHub'da bir konu (issue) açın.

Genel sorular ve tartışmalar için bir GitHub Tartışması başlatın.