Terraform MCP Server

Terraform MCP Server

Le serveur Terraform MCP est un serveur Model Context Protocol (MCP) qui fournit une intégration transparente avec les API du registre Terraform, permettant des capacités avancées d'automatisation et d'interaction pour le développement d'Infrastructure as Code (IaC).

Fonctionnalités

• Support double transport : Transports Stdio et StreamableHTTP avec points de terminaison configurables
• Intégration au registre Terraform : Intégration directe avec les API publiques du registre Terraform pour les fournisseurs, modules et politiques
• Support HCP Terraform et Terraform Enterprise : Gestion complète des espaces de travail, liste 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, balises et gestion des exécutions
• Métriques OTel pour surveiller l'utilisation des outils : Intégration avec les compteurs de télémétrie ouverte pour suivre le volume d'appels d'outils, la latence et les échecs en mode HTTP Streamable. Expose également les métriques par défaut du serveur HTTP 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é pour 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 les outils tiers.

Attention : Les sorties et recommandations fournies par le serveur MCP sont générées dynamiquement et peuvent varier en fonction de la requête, du modèle et du 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 leur 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 pour le 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 ces 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 ces instructions se trouve dans instructions/example-AGENTS.md, pour l'utiliser, validez un fichier nommé AGENTS.md dans le répertoire où résident vos configurations Terraform.

Installation

Utilisation avec Visual Studio Code

Ajoutez le bloc JSON suivant à votre fichier de paramètres utilisateur (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.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"
        ]
      }
    }
  }
}

Optionnellement, vous pouvez ajouter un exemple similaire (c'est-à-dire sans la clé mcp) à un fichier appelé .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.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"
      ]
    }
  }
}

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.1.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 la documentation utilisateur de Claude Desktop. 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.1.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 la documentation utilisateur de Claude Code

• 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 les extensions Gemini

Pour des raisons de sécurité, évitez de coder en dur vos informations d'identification, créez ou mettez à jour ~/.gemini/.env (où ~ est votre répertoire personnel ou de projet) pour stocker les informations d'identification 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.1.0"
      ],
      "disabled": false
    }
  }
}

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

Installer à partir des sources

Utilisez la dernière version publiée :

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

Construire 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. (Facultatif) Tester 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 multiplexeur 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). Celles-ci émettent :

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

Filtrage des outils

Contrôlez les outils disponibles en utilisant --toolsets (groupes) ou --tools (individuel) :

# 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

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

Support des transports

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

1. Transport Stdio (par défaut)

Communication standard d'entrée/sortie 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 SSE (Server-Sent Events). C'est le transport recommandé pour les configurations distantes/distribuées.

Fonctionnalités :

• Point de terminaison : http://{hostname}:8080/mcp
• Vérification de l'état : 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'organisation HCP Terraform autorisés

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) : Conserve l'état de la session entre les requêtes, permettant des opérations contextuelles.
• Mode sans état : Chaque requête est traitée indépendamment sans conserver l'état de la 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 jeton 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 de noms d'organisation HCP Terraform. Le serveur exige Authorization: Bearer <token> et rejette les requêtes à moins que ce jeton puisse accéder à au moins une organisation de la liste 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'organisation est insensible à la casse. Si la valeur CSV configurée ne contient aucun nom d'organisation, le serveur se termine avec une erreur de liste d'autorisation d'organisation mal formée.

Transfert d'IP 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 transférer l'IP du client d'origine vers 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'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é. Activez X-Real-IP ou X-Forwarded-For uniquement 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 d'où 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 vers la 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 se replie sur RemoteAddr.

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

Limitations

• Le serveur ne lit que le premier en-tête X-Forwarded-For d'une requête. Il est valide qu'une requête transporte plusieurs en-têtes X-Forwarded-For, mais la bibliothèque standard de Go ne renvoie que le premier, et le serveur ne les combine pas. Si votre chaîne de proxy é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 se replie sur 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. Cela n'était pas sécurisé, car la valeur la plus à gauche est la plus facile à usurper. La valeur par défaut est désormais RemoteAddr. Si vous exécutez le serveur derrière un proxy et comptez sur X-Forwarded-For pour être transféré vers 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 côté serveur TFE_ADDRESS (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 une erreur 403. Cela empêche un client de rediriger les requêtes, et le jeton Authorization, vers un serveur malveillant.
• 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 du déploiement centralisé pour protéger les jetons en transit.
• Configurez MCP_ALLOWED_ORIGINS pour restreindre les clients pouvant 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.1.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 le certificat CA de votre 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.1.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.1.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, ce 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 (vérifiez 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 pull request

Licence

Ce projet est sous licence open source MPL-2.0. Veuillez vous référer au fichier LICENSE pour les termes complets.

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 bugs et les demandes de fonctionnalités, veuillez ouvrir une issue sur GitHub.

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