Terraform MCP Server

offiziell

HashiCorp Terraform MCP-Server für Infrastructure-as-Code-Workflows, einschließlich Provider- und Modulerkennung über die Terraform Registry.

Was kann man mit Terraform MCP machen?

  • Durchsuchen Sie das öffentliche Terraform Registry — finden Sie Provider und Module per Schlüsselwort mit search_providers und search_modules.
  • Untersuchen Sie Details zu Providern und Modulen — rufen Sie Dokumentation, Versionen und Ein-/Ausgaben mit get_provider_details und get_module_details ab.
  • Verwalten Sie HCP Terraform / TFE Workspaces — listen, erstellen, aktualisieren und löschen Sie Workspaces, einschließlich Variablen und Tags, über list_workspaces und verwandte Tools.
  • Steuern Sie die Ausführung von Runs — listen Sie Runs, wenden Sie Pläne an oder verwerfen Sie sie, und sperren/entsperren Sie Workspaces mit Run-Management-Tools.
  • Greifen Sie auf private Registries zu — suchen und rufen Sie Details aus privaten Provider- und Modul-Registries ab, wenn Sie mit Terraform Enterprise verbunden sind.

Dokumentation

Terraform MCP Server

Der Terraform MCP Server ist ein Model Context Protocol (MCP)-Server, der eine nahtlose Integration mit den Terraform Registry APIs bietet und erweiterte Automatisierungs- und Interaktionsmöglichkeiten für die Infrastructure as Code (IaC)-Entwicklung ermöglicht.

Funktionen

  • Duale Transportunterstützung: Sowohl Stdio- als auch StreamableHTTP-Transporte mit konfigurierbaren Endpunkten
  • Terraform Registry Integration: Direkte Integration mit öffentlichen Terraform Registry APIs für Provider, Module und Richtlinien
  • HCP Terraform & Terraform Enterprise Unterstützung: Vollständige Workspace-Verwaltung, Auflistung von Organisationen/Projekten und Zugriff auf private Registries
  • Workspace-Operationen: Erstellen, Aktualisieren, Löschen von Workspaces mit Unterstützung für Variablen, Tags und Run-Management
  • OTel-Metriken zur Überwachung der Tool-Nutzung: Integration mit Open-Telemetry-Metern zur Verfolgung von Tool-Aufrufvolumen, Latenz und Fehlern im Streamable-HTTP-Modus. Stellt bei Aktivierung dieser Funktion auch standardmäßige HTTP-Server-Metriken bereit

Sicherheitshinweis: Abhängig von der Abfrage kann der MCP-Server bestimmte Terraform-Daten gegenüber dem MCP-Client und dem LLM offenlegen. Verwenden Sie den MCP-Server nicht mit nicht vertrauenswürdigen MCP-Clients oder LLMs.

Rechtlicher Hinweis: Ihre Nutzung eines Drittanbieter-MCP-Clients/LLM unterliegt ausschließlich den Nutzungsbedingungen für diesen MCP/LLM, und IBM ist nicht für die Leistung dieser Drittanbieter-Tools verantwortlich. IBM lehnt ausdrücklich jegliche Gewährleistung und Haftung für Drittanbieter-MCP-Clients/LLMs ab und kann möglicherweise keinen Support zur Behebung von Problemen leisten, die durch die Drittanbieter-Tools verursacht werden.

Vorsicht: Die vom MCP-Server bereitgestellten Ausgaben und Empfehlungen werden dynamisch generiert und können je nach Abfrage, Modell und verbundenem MCP-Client variieren. Benutzer sollten alle Ausgaben/Empfehlungen gründlich überprüfen, um sicherzustellen, dass sie mit den Sicherheits-Best Practices, Kosteneffizienzzielen und Compliance-Anforderungen ihrer Organisation übereinstimmen, bevor sie diese implementieren.

Voraussetzungen

  1. Stellen Sie sicher, dass Docker installiert ist und ausgeführt wird, um den Server in einer containerisierten Umgebung zu verwenden.
  2. Installieren Sie einen KI-Assistenten, der das Model Context Protocol (MCP) unterstützt.

Befehlszeilenoptionen

Umgebungsvariablen:

VariableBeschreibungStandard
TFE_ADDRESSLegt die Terraform Enterprise/HCP Terraform-Adresse für API-Aufrufe fest. Muss das Protokoll enthalten (z. B. https://app.terraform.io). Im streamable-http-Modus ist dies die einzige Möglichkeit, die Adresse festzulegen; sie kann nicht von Clients über Header oder Abfrageparameter bereitgestellt werden.Optional
TFE_TOKENTerraform Enterprise API-Token"" (leer)
TFE_SKIP_TLS_VERIFYTLS-Verifizierung für HCP Terraform oder Terraform Enterprise überspringenfalse
LOG_LEVELProtokollierungsstufe: trace, debug, info, warn, error, fatal, panic (überschreibt das Flag --log-level)info
LOG_FORMATProtokollierungsformat: text oder json (überschreibt das Flag --log-format)text
TRANSPORT_MODEAuf streamable-http setzen, um HTTP-Transport zu aktivieren (veralteter Wert http wird weiterhin unterstützt)stdio
TRANSPORT_HOSTHost, an den der HTTP-Server gebunden wird127.0.0.1
TRANSPORT_PORTHTTP-Server-Port8080
MCP_ENDPOINTHTTP-Server-Endpunktpfad/mcp
MCP_REDIRECT_ROOT_URLURL, an die Anfragen an / umgeleitet werden sollen""
MCP_KEEP_ALIVEKeep-Alive-Intervall für SSE-Verbindungen (z. B. 30s, 1m). 0 zum Deaktivieren0
MCP_SESSION_MODESitzungsmodus: stateful oder statelessstateful
MCP_ALLOWED_ORIGINSDurch Kommas getrennte Liste zulässiger Ursprünge für CORS"" (leer)
MCP_CORS_MODECORS-Modus: strict, development oder disabledstrict
MCP_TLS_CERT_FILEPfad zur TLS-Zertifikatsdatei, erforderlich für Nicht-Localhost-Bereitstellung (z. B. /path/to/cert.pem)"" (leer)
MCP_TLS_KEY_FILEPfad zur TLS-Schlüsseldatei, erforderlich für Nicht-Localhost-Bereitstellung (z. B. /path/to/key.pem)"" (leer)
MCP_RATE_LIMIT_GLOBALGlobale Ratenbegrenzung (Format: rps:burst)10:20
MCP_RATE_LIMIT_SESSIONRatenbegrenzung pro Sitzung (Format: rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTCSV-Liste der HCP Terraform-Organisationsnamen, die auf den HTTP-Server zugreifen dürfen"" (leer)
MCP_FORWARD_CLIENT_IPClient-IP über X-Forwarded-For an HCP Terraform / TFE weiterleiten. Auf true setzen, um zu aktivierenfalse
MCP_REMOTE_IP_METHODWie die Client-IP bei aktivierter Weiterleitung bezogen wird: RemoteAddr (nur direkte Verbindung), X-Real-IP oder X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSAnzahl der vertrauenswürdigen Proxy-Hops, gezählt von rechts der X-Forwarded-For-Kette. Wird nur verwendet, wenn MCP_REMOTE_IP_METHOD=X-Forwarded-For0
ENABLE_TF_OPERATIONSTools aktivieren, die eine explizite Genehmigung erfordernfalse
OTEL_METRICS_ENABLEDTools und Server-Metriken mit Otel aktivierenfalse
OTEL_METRICS_SERVICE_VERSIONVersion des terraform-mcp-servers, der Metriken sendet, die zum Setzen von Metrikattributen verwendet wird. Hilft auch, Metriken über verschiedene Bereitstellungen hinweg zu verfolgenlatest
OTEL_METRICS_SERVICE_NAMEIdentifiziert die Quelle der Metriken (z. B. "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVALSteuert die Häufigkeit von Metrik-Flushes2
OTEL_METRICS_ENDPOINTURL Ihres OTel Collectors oder Backendslocalhost:4318
INSTANA_ENABLEDInstana-Instrumentierung (Metriken und HTTP-Anfrageverfolgung) für den streamable-http-Server aktivieren. Erfordert einen Instana-Agenten, der vom Server aus erreichbar ist.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>]

Anweisungen

Die Standardanweisungen für den MCP-Server befinden sich in cmd/terraform-mcp-server/instructions.md. Wenn diese für die Terraform-Praktiken Ihrer Organisation nicht geeignet erscheinen oder wenn der MCP-Server ungenaue Antworten liefert, ersetzen Sie sie bitte durch Ihre eigenen Anweisungen und erstellen Sie den Container oder die Binärdatei neu. Ein Beispiel für eine solche Anweisung befindet sich in instructions/example-mcp-instructions.md.

AGENTS.md verhält sich im Wesentlichen wie READMEs für Coding-Agenten: ein dedizierter, vorhersehbarer Ort, um den Kontext und die Anweisungen bereitzustellen, die KI-Coding-Agenten bei der Arbeit an Ihrem Projekt unterstützen. Eine AGENTS.md-Datei funktioniert mit verschiedenen Coding-Agenten. Ein Beispiel für eine solche Anweisung befindet sich in instructions/example-AGENTS.md. Um sie zu verwenden, committen Sie eine Datei mit dem Namen AGENTS.md in das Verzeichnis, in dem sich Ihre Terraform-Konfigurationen befinden.

Installation

Verwendung mit Visual Studio Code

Fügen Sie den folgenden JSON-Block zu Ihrer Benutzereinstellungsdatei (JSON) in VS Code hinzu. Sie können dies tun, indem Sie Ctrl + Shift + P drücken und Preferences: Open User Settings (JSON) eingeben.

Weitere Informationen zur Verwendung von MCP-Server-Tools finden Sie in der Agent-Modus-Dokumentation von VS Code.

Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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"
        ]
      }
    }
  }
}

Optional können Sie ein ähnliches Beispiel (d. h. ohne den mcp-Schlüssel) zu einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen. Dadurch können Sie die Konfiguration mit anderen teilen.

Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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)

Verwendung mit Cursor

Fügen Sie dies zu Ihrer Cursor-Konfiguration (~/.cursor/mcp.json) oder über Einstellungen → Cursor-Einstellungen → MCP hinzu:

Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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

Verwendung mit Claude Desktop / Amazon Q Developer / Kiro CLI

Weitere Informationen zur Verwendung von MCP-Server-Tools in Claude Desktop finden Sie in der Benutzerdokumentation. Lesen Sie mehr über die Verwendung des MCP-Servers in Amazon Q Developer und Kiro CLI.

Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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"
      ]
    }
  }
}

Verwendung mit Claude Code

Weitere Informationen zur Verwendung und zum Hinzufügen von MCP-Server-Tools in Claude Code finden Sie in der Benutzerdokumentation

  • Lokaler (stdio) Transport
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Remote (streamable-http) Transport
# 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

Verwendung mit Gemini-Erweiterungen

Vermeiden Sie aus Sicherheitsgründen die Hartcodierung Ihrer Anmeldeinformationen. Erstellen oder aktualisieren Sie ~/.gemini/.env (wobei ~ Ihr Home- oder Projektverzeichnis ist), um HCP Terraform- oder Terraform Enterprise-Anmeldeinformationen zu speichern.

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

Installieren Sie die Erweiterung und führen Sie Gemini aus

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

Verwendung mit Bob IDE / Shell

Weitere Informationen zur Verwendung und zum Hinzufügen von MCP-Server-Tools in Bob IDE oder Shell finden Sie unter Verwendung von MCP in Bob.

Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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
    }
  }
}

Installation aus dem Quellcode

Verwenden Sie die neueste Release-Version:

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

Verwenden Sie den Hauptzweig:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Version 0.3.0+ oder höherVersion 0.2.3 oder niedriger
{
  "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"
      }
    }
  }
}

Lokales Erstellen des Docker-Images

Bevor Sie den Server verwenden, müssen Sie das Docker-Image lokal erstellen:

  1. Klonen Sie das Repository:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Erstellen Sie das Docker-Image:
make docker-build
  1. Dadurch wird ein lokales Docker-Image erstellt, das Sie in der folgenden Konfiguration verwenden können.
# 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

Hinweis: Wenn Sie in Docker ausführen, sollten Sie TRANSPORT_HOST=0.0.0.0 setzen, um Verbindungen von außerhalb des Containers zuzulassen.

  1. (Optional) Testen Sie die Verbindung im HTTP-Modus
# Test the connection
curl http://localhost:8080/health
  1. Sie können es wie folgt in Ihrem KI-Assistenten verwenden:
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Verfügbare Tools

Sehen Sie sich die verfügbaren Tools hier an :link:

Verfügbare Ressourcen

Sehen Sie sich die verfügbaren Ressourcen hier an :link:

Verfügbare Metriken

Es werden zwei Arten von Metriken erfasst. Erstens werden standardmäßige HTTP-Server-Metriken hinzugefügt, indem der HTTP-Mux mit otelhttp.NewHandler(...) umschlossen wird. Dies gibt Folgendes aus:

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

Zweitens zeichnet der MCP-Server benutzerdefinierte Tool-Metriken rund um die Tool-Ausführung mithilfe von MCP-Hooks (BeforeCallTool / AfterCallTool) auf. Diese geben Folgendes aus:

  1. mcp_tool_calls_total
  2. mcp_tool_errors_total
  3. mcp_tool_duration_seconds

Tool-Filterung

Steuern Sie mit --toolsets (Gruppen) oder --tools (einzeln), welche Tools verfügbar sind:

# 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

Verfügbare Toolsets: registry, registry-private, terraform, all, default. Siehe pkg/toolsets/mapping.go für einzelne Tool-Namen. Beide Flags können nicht zusammen verwendet werden.

Transportunterstützung

Der Terraform MCP Server unterstützt mehrere Transportprotokolle:

1. Stdio-Transport (Standard)

Standard-Ein-/Ausgabe-Kommunikation mittels JSON-RPC-Nachrichten. Ideal für die lokale Entwicklung und die direkte Integration mit MCP-Clients.

2. StreamableHTTP-Transport

Moderner HTTP-basierter Transport, der sowohl direkte HTTP-Anfragen als auch Server-Sent Events (SSE)-Streams unterstützt. Dies ist der empfohlene Transport für Remote-/verteilte Setups.

Funktionen:

  • Endpunkt: http://{hostname}:8080/mcp
  • Health Check: http://{hostname}:8080/health
  • Umgebungskonfiguration: Setzen Sie TRANSPORT_MODE=http oder TRANSPORT_PORT=8080 zum Aktivieren
  • Organisations-Zulassungsliste: Setzen Sie MCP_ORGANIZATION_ALLOWLIST oder --organization-allowlist auf eine CSV-Liste erlaubter HCP Terraform-Organisationsnamen

Sitzungsmodi

Der Terraform MCP Server unterstützt bei Verwendung des StreamableHTTP-Transports zwei Sitzungsmodi:

  • Zustandsbehafteter Modus (Standard): Behält den Sitzungszustand zwischen Anfragen bei und ermöglicht kontextbezogene Operationen.
  • Zustandsloser Modus: Jede Anfrage wird unabhängig verarbeitet, ohne den Sitzungszustand beizubehalten, was für hochverfügbare Bereitstellungen oder bei der Verwendung von Load Balancern nützlich sein kann.

Um den zustandslosen Modus zu aktivieren, setzen Sie die Umgebungsvariable:

export MCP_SESSION_MODE=stateless

Token-Durchleitung für zentralisierte Bereitstellungen

Wenn der MCP-Server zentral (StreamableHTTP-Modus) für mehrere Benutzer ausgeführt wird, kann jeder Benutzer sein eigenes Terraform-Token über HTTP-Header zur RBAC-Durchsetzung übergeben. Dies ermöglicht es einer einzelnen Serverinstanz, mehrere Benutzer mit unterschiedlichen Berechtigungen zu bedienen.

Wenn MCP_ORGANIZATION_ALLOWLIST oder --organization-allowlist konfiguriert ist, muss die Zulassungsliste eine CSV-Liste von HCP Terraform-Organisationsnamen sein. Der Server erfordert Authorization: Bearer <token> und lehnt Anfragen ab, es sei denn, dieses Token kann auf mindestens eine Organisation in der CSV-Zulassungsliste zugreifen. Das Bearer-Token hat Vorrang, wenn die Anfrage auch einen TFE_TOKEN-Header enthält, wodurch sichergestellt wird, dass das von der Zulassungsliste validierte Token das für Terraform-API-Anfragen verwendete Token ist. Der Abgleich von Organisationsnamen erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung. Wenn der konfigurierte CSV-Wert zu null Organisationsnamen führt, wird der Server mit einem Fehler wegen fehlerhafter Organisations-Zulassungsliste beendet.

Client-IP-Weiterleitung

Wenn der MCP-Server zentral hinter einem Proxy oder Load Balancer ausgeführt wird, können Sie die IP des ursprünglichen Clients über den X-Forwarded-For-Header an HCP Terraform / TFE weiterleiten. Dies ist standardmäßig deaktiviert und muss mit MCP_FORWARD_CLIENT_IP=true aktiviert werden.

Wenn aktiviert, bezieht der Server die Client-IP gemäß MCP_REMOTE_IP_METHOD:

MethodeVerhalten
RemoteAddr (Standard)Verwendet nur die Adresse der direkten TCP-Verbindung. Ignoriert X-Forwarded-For und X-Real-IP.
X-Real-IPVerwendet den X-Real-IP-Header, wenn es sich um eine gültige IP handelt, andernfalls Fallback auf RemoteAddr.
X-Forwarded-ForVerwendet die X-Forwarded-For-Kette und wählt den Eintrag MCP_XFF_TRUSTED_HOPS Positionen von rechts aus. Fallback auf RemoteAddr, wenn der Wert fehlt oder ungültig ist.

Vertrauensmodell

X-Forwarded-For und X-Real-IP werden von Clients und zwischengeschalteten Proxys gesetzt und können daher gefälscht werden, es sei denn, ein vertrauenswürdiger Proxy vor dem Server überschreibt sie. Aus diesem Grund ist die Standardeinstellung RemoteAddr, die nur dem Peer vertraut, mit dem der Server direkt verbunden ist. Aktivieren Sie X-Real-IP oder X-Forwarded-For nur, wenn sich der Server hinter einem von Ihnen kontrollierten Proxy befindet, der diese Header setzt.

Vertrauenswürdige Hops

Bei Verwendung von X-Forwarded-For ist MCP_XFF_TRUSTED_HOPS die Anzahl der Proxys, die Sie zwischen dem Server und dem Internet betreiben. Hops werden von rechts aus der Kette gezählt, da jeder Proxy die Adresse anhängt, von der er die Anfrage erhalten hat, und der Eintrag ganz rechts von dem Proxy gesetzt wird, der dem Server am nächsten ist. Der Server überspringt diese Anzahl vertrauenswürdiger Einträge und nimmt den nächsten links davon.

Zum Beispiel wählt der Server bei MCP_XFF_TRUSTED_HOPS=1 und einem Header von 200.1.2.3, 10.1.1.10 den Eintrag 200.1.2.3 aus. Bei MCP_XFF_TRUSTED_HOPS=2 und 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1 wählt er 200.1.2.3 aus. Wenn die Hop-Anzahl größer als die Anzahl der Einträge ist oder der ausgewählte Eintrag keine gültige IP ist, fällt der Server auf RemoteAddr zurück.

Eine zu niedrig eingestellte Hop-Anzahl vertraut einem vom Client gelieferten Wert; eine zu hohe Einstellung vertraut einer Adresse weiter innerhalb Ihrer eigenen Infrastruktur. Setzen Sie sie auf die genaue Anzahl der von Ihnen betriebenen Proxys.

Einschränkungen

  • Der Server liest nur den ersten X-Forwarded-For-Header einer Anfrage. Es ist gültig, dass eine Anfrage mehrere X-Forwarded-For-Header enthält, aber die Go-Standardbibliothek gibt nur den ersten zurück, und der Server fügt sie nicht zusammen. Wenn Ihre Proxy-Kette mehrere Header ausgibt, konfigurieren Sie sie so, dass sie einen einzigen kombinierten X-Forwarded-For-Header ausgibt.
  • Sowohl IPv4- als auch IPv6-Adressen werden unterstützt. Werte, die keine gültigen IPs sind, werden abgelehnt, und der Server fällt auf RemoteAddr zurück.

Migration von früheren Versionen

Frühere Versionen verwendeten den linkesten X-Forwarded-For-Wert, wenn der Header vorhanden war, ohne Konfiguration. Dies war unsicher, da der linkeste Wert am leichtesten zu fälschen ist. Der Standard ist jetzt RemoteAddr. Wenn Sie den Server hinter einem Proxy betreiben und sich darauf verlassen, dass X-Forwarded-For an HCP Terraform / TFE weitergeleitet wird, setzen Sie MCP_REMOTE_IP_METHOD=X-Forwarded-For und MCP_XFF_TRUSTED_HOPS auf die Anzahl der von Ihnen betriebenen Proxys.

Unterstützte Header

HeaderBeschreibung
TFE_TOKENTerraform-API-Token
Authorization: Bearer <token>Alternative Methode mit Standard-Bearer-Authentifizierung
TFE_SKIP_TLS_VERIFYTLS-Verifizierung für die Anfrage überspringen

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

Sicherheitsüberlegungen

  • TFE_ADDRESS kann nicht von Clients gesetzt werden. Im streamable-http-Modus wird die Terraform-Adresse nur aus der serverseitigen Umgebungsvariablen TFE_ADDRESS (oder dem Standardwert) bezogen. Anfragen, die versuchen, TFE_ADDRESS über HTTP-Header oder Abfrageparameter zu setzen, werden mit einem 403-Fehler abgelehnt. Dies verhindert, dass ein Client Anfragen und das Authorization-Token an einen bösartigen Server umleitet.
  • Geben Sie Tokens niemals in Abfrageparametern weiter – der Server lehnt solche Anfragen mit einem 400-Fehler ab.
  • Verwenden Sie bei der zentralen Bereitstellung immer TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE), um Tokens während der Übertragung zu schützen.
  • Konfigurieren Sie MCP_ALLOWED_ORIGINS, um einzuschränken, welche Clients sich verbinden können.

Beispiel für eine zentralisierte Bereitstellung

# 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

Benutzer verbinden sich dann mit ihren individuellen Tokens, die über Header übergeben werden, und ermöglichen so eine benutzerbezogene RBAC-Durchsetzung.

Fehlerbehebung

Unternehmensproxy / TLS-Inspektion (Zscaler, etc.)

Wenn Sie sich hinter einem Unternehmensproxy befinden, der TLS-Inspektion durchführt (wie Zscaler Internet Access), können Zertifikatsfehler auftreten:

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

Lösung: Binden Sie das CA-Zertifikat Ihres Unternehmens in den Container ein:

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

Für MCP-Client-Konfigurationen:

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

Alternative: Führen Sie die Binärdatei direkt aus

Wenn Docker in Ihrer Umgebung nicht erlaubt ist, können Sie die Server-Binärdatei direkt installieren und ausführen, die den Zertifikatsspeicher Ihres Systems verwendet:

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

Entwicklung

Voraussetzungen

  • Go (überprüfen Sie die Datei go.mod für die spezifische Version)
  • Docker (optional, für Container-Builds)

Verfügbare Make-Befehle

BefehlBeschreibung
make buildBinärdatei erstellen
make testAlle Tests ausführen
make test-e2eEnd-to-End-Tests ausführen
make docker-buildDocker-Image erstellen
make run-httpHTTP-Server lokal ausführen
make docker-run-httpHTTP-Server in Docker ausführen
make test-httpHTTP-Health-Endpunkt testen
make cleanBuild-Artefakte entfernen
make helpAlle verfügbaren Befehle anzeigen

Mitwirken

  1. Repository forken
  2. Feature-Branch erstellen
  3. Änderungen vornehmen
  4. Tests ausführen
  5. Pull-Request einreichen

Lizenz

Dieses Projekt ist unter den Bedingungen der MPL-2.0 Open-Source-Lizenz lizenziert. Die vollständigen Bedingungen finden Sie in der Datei LICENSE.

Sicherheit

Bei Sicherheitsproblemen wenden Sie sich bitte an security@hashicorp.com oder befolgen Sie unsere Sicherheitsrichtlinie.

Support

Für Fehlerberichte und Funktionsanfragen eröffnen Sie bitte ein Issue auf GitHub.

Für allgemeine Fragen und Diskussionen eröffnen Sie eine GitHub-Diskussion.