Terraform MCP Server

Terraform MCP Server

El Terraform MCP Server es un servidor de Model Context Protocol (MCP) que proporciona integración perfecta con las APIs de Terraform Registry, permitiendo capacidades avanzadas de automatización e interacción para el desarrollo de Infraestructura como Código (IaC).

Características

• Soporte de Transporte Dual: Transportes Stdio y StreamableHTTP con endpoints configurables
• Integración con Terraform Registry: Integración directa con las APIs públicas de Terraform Registry para proveedores, módulos y políticas
• Soporte para HCP Terraform y Terraform Enterprise: Gestión completa de espacios de trabajo, listado de organizaciones/proyectos y acceso al registro privado
• Operaciones de Espacio de Trabajo: Crear, actualizar, eliminar espacios de trabajo con soporte para variables, etiquetas y gestión de ejecuciones
• Métricas OTel para monitorear el uso de herramientas: Integración con medidores de telemetría abierta para rastrear el volumen de llamadas a herramientas, latencia y fallos en modo HTTP Transmisible. También expone métricas predeterminadas del servidor http cuando esta característica está habilitada

Nota de Seguridad: Dependiendo de la consulta, el servidor MCP puede exponer ciertos datos de Terraform al cliente MCP y al LLM. No use el servidor MCP con clientes MCP o LLMs no confiables.

Nota Legal: Su uso de un Cliente MCP/LLM de terceros está sujeto únicamente a los términos de uso de dicho MCP/LLM, e IBM no es responsable del rendimiento de dichas herramientas de terceros. IBM renuncia expresamente a toda garantía y responsabilidad por Clientes MCP/LLMs de terceros, y puede no ser capaz de proporcionar soporte para resolver problemas causados por las herramientas de terceros.

Precaución: Las salidas y recomendaciones proporcionadas por el servidor MCP se generan dinámicamente y pueden variar según la consulta, el modelo y el cliente MCP conectado. Los usuarios deben revisar minuciosamente todas las salidas/recomendaciones para asegurarse de que se alinean con las mejores prácticas de seguridad, objetivos de rentabilidad y requisitos de cumplimiento de su organización antes de la implementación.

Prerrequisitos

1. Asegúrese de que Docker esté instalado y funcionando para usar el servidor en un entorno contenedorizado.
2. Instale un asistente de IA que soporte el Model Context Protocol (MCP).

Opciones de Línea de Comandos

Variables de Entorno:

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

Instrucciones

Las instrucciones predeterminadas para el servidor MCP se encuentran en cmd/terraform-mcp-server/instructions.md, si esas no parecen apropiadas para las prácticas de Terraform de su organización o si el servidor MCP está produciendo respuestas inexactas, por favor reemplácelas con sus propias instrucciones y reconstruya el contenedor o binario. Un ejemplo de tal instrucción se encuentra en instructions/example-mcp-instructions.md

AGENTS.md esencialmente se comporta como READMEs para agentes de codificación: un lugar dedicado y predecible para proporcionar el contexto y las instrucciones para ayudar a los agentes de codificación de IA a trabajar en su proyecto. Un archivo AGENTS.md funciona con diferentes agentes de codificación. Un ejemplo de tal instrucción se encuentra en instructions/example-AGENTS.md, para usarlo, confirme un archivo llamado AGENTS.md en el directorio donde residen sus configuraciones de Terraform.

Instalación

Uso con Visual Studio Code

Agregue el siguiente bloque JSON a su archivo de Configuración de Usuario (JSON) en VS Code. Puede hacer esto presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON).

Más sobre el uso de herramientas del servidor MCP en la documentación del modo agente 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"
        ]
      }
    }
  }
}

Opcionalmente, puede agregar un ejemplo similar (es decir, sin la clave mcp) a un archivo llamado .vscode/mcp.json en su espacio de trabajo. Esto le permitirá compartir la configuración con otros.

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

Uso con Cursor

Agregue esto a su configuración de Cursor (~/.cursor/mcp.json) o vía Configuración → Configuración de 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"
      ]
    }
  }
}

Uso con Claude Desktop / Amazon Q Developer / Kiro CLI

Más sobre el uso de herramientas del servidor MCP en la documentación de usuario de Claude Desktop. Lea más sobre el uso del servidor MCP en Amazon Q Developer y 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"
      ]
    }
  }
}

Uso con Claude Code

Más sobre el uso y adición de herramientas del servidor MCP en la documentación de usuario de Claude Code

• Transporte Local (stdio)

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

• Transporte Remoto (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

Uso con extensiones de Gemini

Por seguridad, evite codificar sus credenciales, cree o actualice ~/.gemini/.env (donde ~ es su directorio de inicio o proyecto) para almacenar las credenciales de HCP Terraform o Terraform Enterprise

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

Instale la extensión y ejecute Gemini

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

Uso con Bob IDE / Shell

Más sobre el uso y adición de herramientas de servidores MCP en Bob IDE o Shell Usando MCP en 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
    }
  }
}

Instalar desde la fuente

Use la última versión de lanzamiento:

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

Use la rama principal:

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

Construyendo la Imagen Docker localmente

Antes de usar el servidor, necesita construir la imagen Docker localmente:

1. Clone el repositorio:

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

2. Construya la imagen Docker:

make docker-build

3. Esto creará una imagen Docker local que puede usar en la siguiente configuración.

# 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

Nota: Al ejecutar en Docker, debe establecer TRANSPORT_HOST=0.0.0.0 para permitir conexiones desde fuera del contenedor.

4. (Opcional) Pruebe la conexión en modo http

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

5. Puede usarlo en su asistente de IA de la siguiente manera:

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

Herramientas Disponibles

Consulte las herramientas disponibles aquí :link:

Recursos Disponibles

Consulte los recursos disponibles aquí :link:

Métricas Disponibles

Se recopilan dos tipos de métricas. Primero, se agregan métricas estándar del servidor HTTP envolviendo el mux HTTP con otelhttp.NewHandler(...). Esto emite:

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

Segundo, el servidor MCP registra métricas de herramientas personalizadas en torno a la ejecución de herramientas usando ganchos MCP (BeforeCallTool / AfterCallTool). Estas emiten:

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

Filtrado de Herramientas

Controle qué herramientas están disponibles usando --toolsets (grupos) o --tools (individual):

# 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

Conjuntos de herramientas disponibles: registry, registry-private, terraform, all, default. Consulte pkg/toolsets/mapping.go para conocer los nombres de las herramientas individuales. No se pueden usar ambos indicadores juntos.

Soporte de transporte

El Terraform MCP Server admite múltiples protocolos de transporte:

1. Transporte Stdio (predeterminado)

Comunicación estándar de entrada/salida mediante mensajes JSON-RPC. Ideal para desarrollo local e integración directa con clientes MCP.

2. Transporte StreamableHTTP

Transporte moderno basado en HTTP que admite tanto solicitudes HTTP directas como flujos de Server-Sent Events (SSE). Este es el transporte recomendado para configuraciones remotas/distribuidas.

Características:

• Endpoint: http://{hostname}:8080/mcp
• Verificación de estado: http://{hostname}:8080/health
• Configuración del entorno: Establezca TRANSPORT_MODE=http o TRANSPORT_PORT=8080 para habilitar
• Lista de permitidos de organizaciones: Establezca MCP_ORGANIZATION_ALLOWLIST o --organization-allowlist en una lista CSV de nombres de organizaciones de HCP Terraform permitidas

Modos de sesión

El Terraform MCP Server admite dos modos de sesión al usar el transporte StreamableHTTP:

• Modo con estado (predeterminado): Mantiene el estado de la sesión entre solicitudes, permitiendo operaciones sensibles al contexto.
• Modo sin estado: Cada solicitud se procesa de forma independiente sin mantener el estado de la sesión, lo que puede ser útil para despliegues de alta disponibilidad o al usar balanceadores de carga.

Para habilitar el modo sin estado, establezca la variable de entorno:

export MCP_SESSION_MODE=stateless

Paso de token para despliegues centralizados

Al ejecutar el servidor MCP de forma centralizada (modo StreamableHTTP) para múltiples usuarios, cada usuario puede pasar su propio token de Terraform a través de cabeceras HTTP para la aplicación de RBAC. Esto permite que una única instancia de servidor atienda a múltiples usuarios con diferentes permisos.

Cuando se configura MCP_ORGANIZATION_ALLOWLIST o --organization-allowlist, la lista de permitidos debe ser una lista CSV de nombres de organizaciones de HCP Terraform. El servidor requiere Authorization: Bearer <token> y rechaza las solicitudes a menos que ese token pueda acceder al menos a una organización en la lista CSV de permitidos. El token de portador tiene prioridad si la solicitud también incluye una cabecera TFE_TOKEN, asegurando que el token validado por la lista de permitidos sea el token utilizado para las solicitudes a la API de Terraform. La coincidencia de nombres de organización no distingue entre mayúsculas y minúsculas. Si el valor CSV configurado se analiza como cero nombres de organización, el servidor finaliza con un error de lista de permitidos de organizaciones mal formada.

Reenvío de IP del cliente

Al ejecutar el servidor MCP de forma centralizada detrás de un proxy o balanceador de carga, puede reenviar la IP del cliente de origen a HCP Terraform / TFE a través de la cabecera X-Forwarded-For. Esto está desactivado de forma predeterminada y debe habilitarse con MCP_FORWARD_CLIENT_IP=true.

Cuando está habilitado, el servidor obtiene la IP del cliente de acuerdo con MCP_REMOTE_IP_METHOD:

Modelo de confianza

X-Forwarded-For y X-Real-IP son establecidos por los clientes y los proxies intermediarios, por lo que pueden ser suplantados a menos que un proxy de confianza frente al servidor los sobrescriba. Por esta razón, el valor predeterminado es RemoteAddr, que confía solo en el par al que el servidor está conectado directamente. Habilite X-Real-IP o X-Forwarded-For solo cuando el servidor se encuentre detrás de un proxy que usted controle y que establezca estas cabeceras.

Saltos de confianza

Al usar X-Forwarded-For, MCP_XFF_TRUSTED_HOPS es el número de proxies que opera entre el servidor e internet. Los saltos se cuentan desde la derecha de la cadena, ya que cada proxy añade la dirección desde la que recibió la solicitud y la entrada más a la derecha es establecida por el proxy más cercano al servidor. El servidor omite ese número de entradas de confianza y toma la siguiente a la izquierda.

Por ejemplo, con MCP_XFF_TRUSTED_HOPS=1 y una cabecera de 200.1.2.3, 10.1.1.10, el servidor selecciona 200.1.2.3. Con MCP_XFF_TRUSTED_HOPS=2 y 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1, selecciona 200.1.2.3. Si el recuento de saltos es mayor que el número de entradas, o la entrada seleccionada no es una IP válida, el servidor recurre a RemoteAddr.

Establecer el recuento de saltos demasiado bajo confiará en un valor proporcionado por el cliente; establecerlo demasiado alto confiará en una dirección más adentro de su propia infraestructura. Establézcalo en el número exacto de proxies que opera.

Limitaciones

• El servidor lee solo la primera cabecera X-Forwarded-For en una solicitud. Es válido que una solicitud lleve múltiples cabeceras X-Forwarded-For, pero la biblioteca estándar de Go devuelve solo la primera, y el servidor no las une. Si su cadena de proxies emite múltiples cabeceras, configúrela para que emita una única cabecera X-Forwarded-For combinada.
• Se admiten direcciones IPv4 e IPv6. Los valores que no son IPs válidas se rechazan y el servidor recurre a RemoteAddr.

Migración desde versiones anteriores

Las versiones anteriores utilizaban el valor más a la izquierda de X-Forwarded-For cuando la cabecera estaba presente, sin configuración. Esto era inseguro, ya que el valor más a la izquierda es el más fácil de suplantar. El valor predeterminado ahora es RemoteAddr. Si ejecuta el servidor detrás de un proxy y depende de que X-Forwarded-For se reenvíe a HCP Terraform / TFE, establezca MCP_REMOTE_IP_METHOD=X-Forwarded-For y MCP_XFF_TRUSTED_HOPS en el número de proxies que opera.

Cabeceras admitidas

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

Consideraciones de seguridad

• TFE_ADDRESS no puede ser establecido por los clientes. En modo streamable-http, la dirección de Terraform se obtiene solo de la variable de entorno del lado del servidor TFE_ADDRESS (o el valor predeterminado). Las solicitudes que intenten establecer TFE_ADDRESS mediante cabecera HTTP o parámetro de consulta se rechazan con un error 403. Esto evita que un cliente redirija las solicitudes, y el token Authorization, a un servidor malicioso.
• Nunca pase tokens en parámetros de consulta - el servidor rechazará dichas solicitudes con un error 400.
• Utilice siempre TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) al desplegar de forma centralizada para proteger los tokens en tránsito.
• Configure MCP_ALLOWED_ORIGINS para restringir qué clientes pueden conectarse.

Ejemplo de despliegue centralizado

# 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

Luego, los usuarios se conectan con sus tokens individuales pasados a través de cabeceras, lo que permite la aplicación de RBAC por usuario.

Solución de problemas

Proxy corporativo / Inspección TLS (Zscaler, etc.)

Si se encuentra detrás de un proxy corporativo que realiza inspección TLS (como Zscaler Internet Access), puede ver errores de certificado:

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

Solución: Monte su certificado de CA corporativa en el contenedor:

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

Para configuraciones de cliente 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"
      ]
    }
  }
}

Alternativa: Ejecute el binario directamente

Si Docker no está permitido en su entorno, puede instalar y ejecutar el binario del servidor directamente, que utilizará el almacén de certificados de su sistema:

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

Desarrollo

Requisitos previos

• Go (consulte el archivo go.mod para la versión específica)
• Docker (opcional, para compilaciones de contenedores)

Comandos Make disponibles

Contribuciones

1. Bifurque el repositorio
2. Cree su rama de funcionalidad
3. Realice sus cambios
4. Ejecute las pruebas
5. Envíe una solicitud de extracción

Licencia

Este proyecto está licenciado bajo los términos de la licencia de código abierto MPL-2.0. Consulte el archivo LICENSE para los términos completos.

Seguridad

Para problemas de seguridad, comuníquese con security@hashicorp.com o siga nuestra política de seguridad.

Soporte

Para informes de errores y solicitudes de funcionalidades, abra un issue en GitHub.

Para preguntas y debates generales, abra un GitHub Discussion.