Terraform MCP Server

Terraform MCP Server

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

Tabla de Contenidos

Características

• Soporte de doble transporte: 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 de HCP Terraform y Terraform Enterprise: Gestión completa de workspaces, listado de organizaciones/proyectos y acceso a registros privados
• Operaciones de workspace: Crear, actualizar y eliminar workspaces con soporte para variables, etiquetas y gestión de ejecuciones
• Métricas OTel para monitoreo del uso de herramientas: Integración con medidores de open telemetry para rastrear el volumen de llamadas a herramientas, latencia y fallos en modo Streamable HTTP. 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 utilice el servidor MCP con clientes MCP o LLM 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 todas y cada una de las garantías y responsabilidades por Clientes MCP/LLM de terceros, y puede que no pueda brindar 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 alineen con las mejores prácticas de seguridad, los objetivos de eficiencia de costos y los requisitos de cumplimiento de su organización antes de la implementación.

Requisitos previos

1. Asegúrese de que Docker esté instalado y en ejecución para usar el servidor en un entorno contenedorizado.
2. Instale un asistente de IA que admita 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 no parecen apropiadas para las prácticas de Terraform de su organización o si el servidor MCP produce respuestas inexactas, reemplácelas con sus propias instrucciones y reconstruya el contenedor o binario. Un ejemplo de dicha 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 e instrucciones que ayuden 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 dicha 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 hacerlo presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON).

Más información 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.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"
        ]
      }
    }
  }
}

Opcionalmente, puede agregar un ejemplo similar (es decir, sin la clave mcp) a un archivo llamado .vscode/mcp.json en su workspace. 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.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"
      ]
    }
  }
}

Uso con Cursor

Agregue esto a su configuración de Cursor (~/.cursor/mcp.json) o mediante 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.3.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 información sobre el uso de herramientas del servidor MCP en Claude Desktop documentación de usuario. 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.3.0"
      ]
    }
  }
}

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

Uso con Claude Code

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

• 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 Codex CLI

Más información sobre el uso y la adición de herramientas del servidor MCP en Codex CLI documentación de usuario.

Nota: Agregue TFE_ADDRESS y TFE_TOKEN a los comandos de Docker para herramientas autenticadas de HCP Terraform o Terraform Enterprise.

• Transporte local (stdio)

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

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

Uso con extensiones de Gemini

Por seguridad, evite codificar sus credenciales; cree o actualice ~/.gemini/.env (donde ~ es su directorio de inicio o de proyecto) para almacenar 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 información sobre el uso y la adición de herramientas del servidor MCP en Bob IDE o Shell Uso de 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.3.0"
      ],
      "disabled": false
    }
  }
}

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

Instalar desde el código fuente

Use la versión de lanzamiento más reciente:

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

Construcción de la imagen Docker localmente

Antes de usar el servidor, debe 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: Cuando se ejecuta 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 al envolver 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 personalizadas de herramientas alrededor de la ejecución de herramientas usando hooks de 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 (individuales):

# 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 nombres de herramientas individuales. No puede usar ambas banderas juntas.

Soporte de transporte

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

1. Transporte Stdio (predeterminado)

Comunicación estándar de entrada/salida usando 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 Eventos Enviados por el Servidor (SSE). Este es el transporte recomendado para configuraciones remotas/distribuidas.

Características:

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

Modos de sesión

El servidor Terraform MCP admite dos modos de sesión cuando se usa el transporte StreamableHTTP:

• Modo con estado (predeterminado): Mantiene el estado de la sesión entre solicitudes, lo que permite operaciones conscientes del 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 implementaciones de alta disponibilidad o cuando se usan balanceadores de carga.

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

export MCP_SESSION_MODE=stateless

Paso de tokens para implementaciones centralizadas

Cuando se ejecuta 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 encabezados HTTP para la aplicación de RBAC. Esto permite que una única instancia del 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 HCP Terraform. El servidor requiere Authorization: Bearer <token> y rechaza solicitudes a menos que ese token pueda acceder a al menos una organización en la lista CSV de permitidos. El token de portador tiene prioridad si la solicitud también incluye un encabezado TFE_TOKEN, lo que garantiza que el token validado por la lista de permitidos sea el token utilizado para las solicitudes de API de Terraform. La coincidencia de nombres de organizaciones no distingue entre mayúsculas y minúsculas. Si el valor CSV configurado se analiza en cero nombres de organizaciones, el servidor sale con un error de lista de permitidos de organizaciones mal formada.

Reenvío de IP del cliente

Cuando se ejecuta el servidor MCP de forma centralizada detrás de un proxy o balanceador de carga, puede reenviar la IP del cliente originario a HCP Terraform / TFE a través del encabezado X-Forwarded-For. Esto está desactivado por defecto y debe habilitarse con MCP_FORWARD_CLIENT_IP=true.

Cuando está habilitado, el servidor obtiene la IP del cliente según MCP_REMOTE_IP_METHOD:

Modelo de confianza

X-Forwarded-For y X-Real-IP son establecidos por clientes y proxies intermediarios, por lo que pueden ser falsificados 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. Solo habilite X-Real-IP o X-Forwarded-For cuando el servidor esté detrás de un proxy que usted controle y que establezca estos encabezados.

Saltos de confianza

Cuando se usa X-Forwarded-For, MCP_XFF_TRUSTED_HOPS es el número de proxies que usted opera entre el servidor e Internet. Los saltos se cuentan desde la derecha de la cadena, ya que cada proxy agrega 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 esa cantidad de entradas de confianza y toma la siguiente a la izquierda.

Por ejemplo, con MCP_XFF_TRUSTED_HOPS=1 y un encabezado 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 número 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 número 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 usted ejecuta.

Limitaciones

• El servidor lee solo el primer encabezado X-Forwarded-For en una solicitud. Es válido que una solicitud lleve múltiples encabezados X-Forwarded-For, pero la biblioteca estándar de Go devuelve solo el primero, y el servidor no los une. Si su cadena de proxies emite múltiples encabezados, configúrela para que emita un único encabezado X-Forwarded-For combinado.
• 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 usaban el valor X-Forwarded-For más a la izquierda cuando el encabezado estaba presente, sin configuración. Esto era inseguro, ya que el valor más a la izquierda es el más fácil de falsificar. 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 al número de proxies que usted opera.

Encabezados admitidos

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 TFE_ADDRESS del lado del servidor (o el valor predeterminado). Las solicitudes que intentan establecer TFE_ADDRESS a través de un encabezado HTTP o parámetro de consulta se rechazan con un 403. Esto evita que un cliente redirija solicitudes, y el token Authorization, a un servidor malicioso.
• Identificación de implementación alojada: establecer TF_MCP_SHARED_SECRET envía ese valor como el encabezado X-Tf-Mcp-Secret en cada solicitud de HCP Terraform / TFE, lo que permite al backend identificar solicitudes de una implementación alojada conocida (por ejemplo, para aplicar listas de permitidos de IP). Es un secreto estático enviado en un encabezado, así que úselo solo sobre TLS y trate el valor como una credencial.
• Nunca pase tokens en parámetros de consulta - el servidor rechazará tales solicitudes con un error 400.
• Use siempre TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) al implementar de forma centralizada para proteger los tokens en tránsito.
• Configure MCP_ALLOWED_ORIGINS para restringir qué clientes pueden conectarse.

Ejemplo de implementación centralizada

# 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

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

Solución de problemas

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

Si está 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 CA corporativo 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.3.0

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

Alternativa: Ejecute el binario directamente

Si Docker no está permitido en su entorno, puede instalar y ejecutar el binario del servidor directamente, que usará 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. Haz un fork del repositorio
2. Crea tu rama de características
3. Realiza tus cambios
4. Ejecuta las pruebas
5. Envía una solicitud de extracción (pull request)

Licencia

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

Seguridad

Para problemas de seguridad, contacta a security@hashicorp.com o sigue nuestra política de seguridad.

Soporte

Para informes de errores y solicitudes de funciones, abre un issue en GitHub.

Para preguntas generales y discusiones, abre una Discusión de GitHub.