Terraform MCP Server

Serveur MCP Terraform

Le serveur MCP Terraform est un serveur Model Context Protocol (MCP) qui s'intègre de manière transparente avec les API Terraform Registry et HCP Terraform, permettant des capacités avancées d'automatisation et d'interaction pour le développement d'Infrastructure as Code (IaC).

Table des matières

Fonctionnalités

• Support de double transport : Transports Stdio et StreamableHTTP avec points de terminaison configurables
• Intégration Terraform Registry : Intégration directe avec les API publiques de Terraform Registry pour les providers, modules et politiques
• Support HCP Terraform et Terraform Enterprise : Gestion complète des espaces de travail, listage des organisations/projets et accès au registre privé
• Opérations sur les espaces de travail : Créer, mettre à jour, supprimer des espaces de travail avec prise en charge des variables, étiquettes et gestion des exécutions
• Métriques OTel pour la surveillance de l'utilisation des outils : Intégration avec les compteurs open telemetry pour suivre le volume d'appels d'outils, la latence et les échecs en mode Streamable HTTP. Expose également les métriques HTTP serveur par défaut lorsque cette fonctionnalité est activée

Note de sécurité : Selon la requête, le serveur MCP peut exposer certaines données Terraform au client MCP et au LLM. N'utilisez pas le serveur MCP avec des clients MCP ou des LLM non fiables.

Note légale : Votre utilisation d'un client MCP/LLM tiers est soumise uniquement aux conditions d'utilisation de ce MCP/LLM, et IBM n'est pas responsable des performances de ces outils tiers. IBM décline expressément toute garantie et responsabilité concernant les clients MCP/LLM tiers, et peut ne pas être en mesure de fournir un support pour résoudre les problèmes causés par ces outils tiers.

Attention : Les sorties et recommandations fournies par le serveur MCP sont générées dynamiquement et peuvent varier selon la requête, le modèle et le client MCP connecté. Les utilisateurs doivent examiner attentivement toutes les sorties/recommandations pour s'assurer qu'elles correspondent aux meilleures pratiques de sécurité, aux objectifs de rentabilité et aux exigences de conformité de leur organisation avant la mise en œuvre.

Prérequis

1. Assurez-vous que Docker est installé et en cours d'exécution pour utiliser le serveur dans un environnement conteneurisé.
2. Installez un assistant IA prenant en charge le Model Context Protocol (MCP).

Options de ligne de commande

Variables d'environnement :

# 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>]

Instructions

Les instructions par défaut du serveur MCP se trouvent dans cmd/terraform-mcp-server/instructions.md. Si celles-ci ne semblent pas appropriées pour les pratiques Terraform de votre organisation ou si le serveur MCP produit des réponses inexactes, veuillez les remplacer par vos propres instructions et reconstruire le conteneur ou le binaire. Un exemple de telles instructions se trouve dans instructions/example-mcp-instructions.md

AGENTS.md se comporte essentiellement comme des README pour les agents de codage : un endroit dédié et prévisible pour fournir le contexte et les instructions afin d'aider les agents de codage IA à travailler sur votre projet. Un fichier AGENTS.md fonctionne avec différents agents de codage. Un exemple de telles instructions se trouve dans instructions/example-AGENTS.md. Pour l'utiliser, committez un fichier nommé AGENTS.md dans le répertoire où se trouvent vos configurations Terraform.

Installation

Utilisation avec Visual Studio Code

Ajoutez le bloc JSON suivant à votre fichier User Settings (JSON) dans VS Code. Vous pouvez le faire en appuyant sur Ctrl + Shift + P et en tapant Preferences: Open User Settings (JSON).

En savoir plus sur l'utilisation des outils du serveur MCP dans la documentation du mode agent de 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.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"
        ]
      }
    }
  }
}

Optionnellement, vous pouvez ajouter un exemple similaire (c'est-à-dire sans la clé mcp) à un fichier nommé .vscode/mcp.json dans votre espace de travail. Cela vous permettra de partager la configuration avec d'autres.

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

Utilisation avec Cursor

Ajoutez ceci à votre configuration Cursor (~/.cursor/mcp.json) ou via Paramètres → Paramètres 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.3.0"
      ]
    }
  }
}

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

Utilisation avec Claude Desktop / Amazon Q Developer / Kiro CLI

En savoir plus sur l'utilisation des outils du serveur MCP dans Claude Desktop documentation utilisateur. En savoir plus sur l'utilisation du serveur MCP dans Amazon Q Developer et 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.3.0"
      ]
    }
  }
}

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

Utilisation avec Claude Code

En savoir plus sur l'utilisation et l'ajout d'outils de serveur MCP dans Claude Code documentation utilisateur

• Transport local (stdio)

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

• Transport distant (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

Utilisation avec Codex CLI

En savoir plus sur l'utilisation et l'ajout d'outils de serveur MCP dans Codex CLI documentation utilisateur.

Remarque : Ajoutez TFE_ADDRESS et TFE_TOKEN aux commandes Docker pour les outils HCP Terraform ou Terraform Enterprise authentifiés.

• Transport local (stdio)

codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

• Transport distant (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

Utilisation avec les extensions Gemini

Par sécurité, évitez de coder en dur vos identifiants, créez ou mettez à jour ~/.gemini/.env (où ~ est votre répertoire personnel ou projet) pour stocker les identifiants HCP Terraform ou Terraform Enterprise

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

Installez l'extension et exécutez Gemini

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

Utilisation avec Bob IDE / Shell

En savoir plus sur l'utilisation et l'ajout d'outils de serveurs MCP dans Bob IDE ou Shell Utilisation de MCP dans 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.3.0"
      ],
      "disabled": false
    }
  }
}

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

Installation à partir des sources

Utilisez la version de la dernière version :

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

Utilisez la branche principale :

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

Construction de l'image Docker localement

Avant d'utiliser le serveur, vous devez construire l'image Docker localement :

1. Clonez le dépôt :

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

2. Construisez l'image Docker :

make docker-build

3. Cela créera une image Docker locale que vous pourrez utiliser dans la configuration suivante.

# 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

Remarque : Lors de l'exécution dans Docker, vous devez définir TRANSPORT_HOST=0.0.0.0 pour autoriser les connexions depuis l'extérieur du conteneur.

4. (Optionnel) Testez la connexion en mode http

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

5. Vous pouvez l'utiliser sur votre assistant IA comme suit :

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

Outils disponibles

Consultez les outils disponibles ici :link:

Ressources disponibles

Consultez les ressources disponibles ici :link:

Métriques disponibles

Deux types de métriques sont collectées. Premièrement, les métriques standard du serveur HTTP sont ajoutées en enveloppant le mux HTTP avec otelhttp.NewHandler(...). Cela émet :

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

Deuxièmement, le serveur MCP enregistre des métriques d'outils personnalisées autour de l'exécution des outils en utilisant les hooks MCP (BeforeCallTool / AfterCallTool). Cela émet :

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

Filtrage des outils

Contrôlez quels outils sont disponibles en utilisant --toolsets (groupes) ou --tools (individuels) :

# 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

Ensembles d'outils disponibles : registry, registry-private, terraform, all, default. Voir pkg/toolsets/mapping.go pour les noms d'outils individuels. Impossible d'utiliser les deux indicateurs ensemble.

Prise en charge des transports

Le serveur Terraform MCP prend en charge plusieurs protocoles de transport :

1. Transport Stdio (par défaut)

Communication d'entrée/sortie standard utilisant des messages JSON-RPC. Idéal pour le développement local et l'intégration directe avec les clients MCP.

2. Transport StreamableHTTP

Transport moderne basé sur HTTP prenant en charge à la fois les requêtes HTTP directes et les flux Server-Sent Events (SSE). C'est le transport recommandé pour les configurations distantes/distribuées.

Caractéristiques :

• Point de terminaison : http://{hostname}:8080/mcp
• Vérification de santé : http://{hostname}:8080/health
• Configuration de l'environnement : Définissez TRANSPORT_MODE=http ou TRANSPORT_PORT=8080 pour activer
• Liste d'autorisation des organisations : Définissez MCP_ORGANIZATION_ALLOWLIST ou --organization-allowlist sur une liste CSV des noms d'organisations HCP Terraform autorisées

Modes de session

Le serveur Terraform MCP prend en charge deux modes de session lors de l'utilisation du transport StreamableHTTP :

• Mode avec état (par défaut) : Maintient l'état de session entre les requêtes, permettant des opérations contextuelles.
• Mode sans état : Chaque requête est traitée indépendamment sans maintenir l'état de session, ce qui peut être utile pour les déploiements à haute disponibilité ou lors de l'utilisation d'équilibreurs de charge.

Pour activer le mode sans état, définissez la variable d'environnement :

export MCP_SESSION_MODE=stateless

Transmission de jetons pour les déploiements centralisés

Lors de l'exécution du serveur MCP de manière centralisée (mode StreamableHTTP) pour plusieurs utilisateurs, chaque utilisateur peut transmettre son propre jeton Terraform via les en-têtes HTTP pour l'application du RBAC. Cela permet à une seule instance de serveur de servir plusieurs utilisateurs avec des autorisations différentes.

Lorsque MCP_ORGANIZATION_ALLOWLIST ou --organization-allowlist est configuré, la liste d'autorisation doit être une liste CSV des noms d'organisations HCP Terraform. Le serveur exige Authorization: Bearer <token> et rejette les requêtes à moins que ce jeton puisse accéder à au moins une organisation dans la liste d'autorisation CSV. Le jeton porteur a priorité si la requête inclut également un en-tête TFE_TOKEN, garantissant que le jeton validé par la liste d'autorisation est le jeton utilisé pour les requêtes API Terraform. La correspondance des noms d'organisations est insensible à la casse. Si la valeur CSV configurée est analysée en zéro nom d'organisation, le serveur se termine avec une erreur de liste d'autorisation d'organisation mal formée.

Transmission de l'adresse IP du client

Lors de l'exécution du serveur MCP de manière centralisée derrière un proxy ou un équilibreur de charge, vous pouvez transmettre l'adresse IP du client d'origine à HCP Terraform / TFE via l'en-tête X-Forwarded-For. Ceci est désactivé par défaut et doit être activé avec MCP_FORWARD_CLIENT_IP=true.

Lorsqu'il est activé, le serveur source l'adresse IP du client selon MCP_REMOTE_IP_METHOD :

Modèle de confiance

X-Forwarded-For et X-Real-IP sont définis par les clients et les proxys intermédiaires, ils peuvent donc être usurpés à moins qu'un proxy de confiance devant le serveur ne les écrase. Pour cette raison, la valeur par défaut est RemoteAddr, qui ne fait confiance qu'au pair auquel le serveur est directement connecté. N'activez X-Real-IP ou X-Forwarded-For que lorsque le serveur se trouve derrière un proxy que vous contrôlez et qui définit ces en-têtes.

Sauts de confiance

Lors de l'utilisation de X-Forwarded-For, MCP_XFF_TRUSTED_HOPS est le nombre de proxys que vous exploitez entre le serveur et Internet. Les sauts sont comptés depuis la droite de la chaîne, car chaque proxy ajoute l'adresse à partir de laquelle il a reçu la requête et l'entrée la plus à droite est définie par le proxy le plus proche du serveur. Le serveur ignore ce nombre d'entrées de confiance et prend la suivante à gauche.

Par exemple, avec MCP_XFF_TRUSTED_HOPS=1 et un en-tête de 200.1.2.3, 10.1.1.10, le serveur sélectionne 200.1.2.3. Avec MCP_XFF_TRUSTED_HOPS=2 et 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1, il sélectionne 200.1.2.3. Si le nombre de sauts est supérieur au nombre d'entrées, ou si l'entrée sélectionnée n'est pas une IP valide, le serveur revient à RemoteAddr.

Définir le nombre de sauts trop bas fera confiance à une valeur fournie par le client ; le définir trop haut fera confiance à une adresse plus profonde dans votre propre infrastructure. Définissez-le sur le nombre exact de proxys que vous exécutez.

Limitations

• Le serveur lit uniquement le premier en-tête X-Forwarded-For sur une requête. Il est valide qu'une requête porte plusieurs en-têtes X-Forwarded-For, mais la bibliothèque standard de Go ne renvoie que le premier, et le serveur ne les joint pas. Si votre chaîne de proxys émet plusieurs en-têtes, configurez-la pour émettre un seul en-tête X-Forwarded-For combiné.
• Les adresses IPv4 et IPv6 sont toutes deux prises en charge. Les valeurs qui ne sont pas des IP valides sont rejetées et le serveur revient à RemoteAddr.

Migration depuis les versions antérieures

Les versions antérieures utilisaient la valeur X-Forwarded-For la plus à gauche lorsque l'en-tête était présent, sans configuration. C'était peu sûr, car la valeur la plus à gauche est la plus facilement usurpable. La valeur par défaut est maintenant RemoteAddr. Si vous exécutez le serveur derrière un proxy et que vous comptez sur X-Forwarded-For pour être transmis à HCP Terraform / TFE, définissez MCP_REMOTE_IP_METHOD=X-Forwarded-For et MCP_XFF_TRUSTED_HOPS sur le nombre de proxys que vous exploitez.

En-têtes pris en charge

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

Considérations de sécurité

• TFE_ADDRESS ne peut pas être défini par les clients. En mode streamable-http, l'adresse Terraform provient uniquement de la variable d'environnement TFE_ADDRESS côté serveur (ou de la valeur par défaut). Les requêtes qui tentent de définir TFE_ADDRESS via un en-tête HTTP ou un paramètre de requête sont rejetées avec un 403. Cela empêche un client de rediriger les requêtes, et le jeton Authorization, vers un serveur malveillant.
• Identification du déploiement hébergé : définir TF_MCP_SHARED_SECRET envoie cette valeur comme en-tête X-Tf-Mcp-Secret sur chaque requête HCP Terraform / TFE, permettant au backend d'identifier les requêtes provenant d'un déploiement hébergé connu (par exemple, pour appliquer des listes d'autorisation IP). C'est un secret statique envoyé dans un en-tête, donc utilisez-le uniquement sur TLS et traitez la valeur comme un identifiant.
• Ne transmettez jamais de jetons dans les paramètres de requête - le serveur rejettera ces requêtes avec une erreur 400.
• Utilisez toujours TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) lors d'un déploiement centralisé pour protéger les jetons en transit.
• Configurez MCP_ALLOWED_ORIGINS pour restreindre les clients qui peuvent se connecter.

Exemple de déploiement centralisé

# 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

Les utilisateurs se connectent ensuite avec leurs jetons individuels transmis via les en-têtes, permettant l'application du RBAC par utilisateur.

Dépannage

Proxy d'entreprise / Inspection TLS (Zscaler, etc.)

Si vous êtes derrière un proxy d'entreprise qui effectue une inspection TLS (comme Zscaler Internet Access), vous pouvez voir des erreurs de certificat :

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

Solution : Montez votre certificat CA d'entreprise dans le conteneur :

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

Pour les configurations client 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"
      ]
    }
  }
}

Alternative : Exécutez le binaire directement

Si Docker n'est pas autorisé dans votre environnement, vous pouvez installer et exécuter le binaire du serveur directement, qui utilisera le magasin de certificats de votre système :

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

Développement

Prérequis

• Go (consultez le fichier go.mod pour la version spécifique)
• Docker (optionnel, pour les builds de conteneurs)

Commandes Make disponibles

Contribution

1. Forkez le dépôt
2. Créez votre branche de fonctionnalité
3. Apportez vos modifications
4. Exécutez les tests
5. Soumettez une demande d'extraction (pull request)

Licence

Ce projet est sous licence open source MPL-2.0. Veuillez consulter le fichier LICENSE pour les conditions complètes.

Sécurité

Pour les problèmes de sécurité, veuillez contacter security@hashicorp.com ou suivre notre politique de sécurité.

Support

Pour les rapports de bogues et les demandes de fonctionnalités, veuillez ouvrir un problème (issue) sur GitHub.

Pour les questions générales et les discussions, ouvrez une discussion GitHub.