terraform-mcp-server

MCP (Model Context Protocol) server para gestionar los módulos de Terraform de la organización <TuOrg> en GitHub.

Este server expone tools que permiten a los agentes de IA buscar, inspeccionar y scaffoldear configuraciones de Terraform usando la librería de módulos privados de la organización (repos con el nombre terraform-aws-module-*).

Funcionalidades

• search_modules — Lista y filtra los módulos de Terraform disponibles en la organización
• get_module — Obtiene el detalle del módulo: README, variables, outputs y última versión
• list_module_versions — Lista todos los tags de versión disponibles de un módulo
• scaffold_terraform — Genera una configuración completa de Terraform usando un módulo

Instalación

# Clona el repositorio
git clone https://github.com/<TuOrg>/terraform-mcp-server.git
cd terraform-mcp-server

# Instala con pip
pip install -e .

# O con uv
uv pip install -e .

Variables de entorno

Variable	Obligatoria	Default	Descripción
GITHUB_TOKEN	Sí	—	Personal access token de GitHub con scope repo
GITHUB_ORG	Sí	<TuOrg> (placeholder)	Nombre de la organización de GitHub — el default es un placeholder, hay que definirla
MODULE_PREFIX	No	terraform-aws-module-	Prefijo de los repos de módulos
TF_MIN_VERSION	No	1.10	Versión mínima de Terraform en las configuraciones generadas (1.10+ es necesario para el locking nativo de state en S3)
IAC_ROLE_NAME	No	terraform-iac	Rol IAM que asume el provider generado — el assume_role se emite siempre, nunca se usan credenciales estáticas

Uso

Arrancar el server

# Directamente
terraform-mcp-server

# O como módulo de Python
python -m terraform_mcp_server.server

Configuración del cliente MCP

Agrégalo a la configuración de tu cliente MCP (por ejemplo, Claude Desktop, Kiro, etc.):

{
  "mcpServers": {
    "terraform-mcp-server": {
      "command": "terraform-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

O si lo ejecutas desde el código fuente con uv:

{
  "mcpServers": {
    "terraform-mcp-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/terraform-mcp-server", "terraform-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Referencia de tools

search_modules

Busca los módulos de Terraform disponibles en la organización.

Parámetros:

• query (str, opcional): filtra los módulos por nombre de servicio

Ejemplo de respuesta:

{
  "count": 2,
  "modules": [
    {
      "name": "terraform-aws-module-vpc",
      "service_name": "vpc",
      "description": "Terraform module for AWS VPC",
      "last_updated": "2024-01-15T10:30:00Z",
      "default_branch": "main"
    }
  ]
}

get_module

Obtiene información detallada de un módulo concreto.

Parámetros:

• service_name (str, obligatorio): nombre del servicio (por ejemplo, "vpc", "ec2")

list_module_versions

Lista todas las versiones disponibles (tags git) de un módulo.

Parámetros:

• service_name (str, obligatorio): nombre del servicio

scaffold_terraform

Genera una configuración completa de Terraform usando un módulo.

Parámetros:

• service_name (str, obligatorio): nombre del servicio
• variables (dict, opcional): valores de variables para precargar

Archivos generados:

• versions.tf — Bloque terraform (required_version, required_providers)
• providers.tf — Configuración del provider (region + assume_role obligatorio sobre terraform-iac + default_tags)
• variables.tf — Variables comunes + propias del módulo
• terraform.tfvars — Valores de las variables (con placeholders)
• main.tf — Llamada al módulo
• outputs.tf — Outputs del módulo
• data.tf — Placeholder de data sources

El bloque provider incluye siempre assume_role. aws_account_id es una variable obligatoria (validada a 12 dígitos) y sin default — Terraform no se ejecuta hasta que se indique la cuenta propietaria del rol terraform-iac.

get_backend_config

Obtiene la configuración del backend S3 (bucket, key, region) según team, project y environment. El bloque devuelto va en backend.tf (campo file de la respuesta).

Parámetros:

• team (str, obligatorio): nombre del equipo
• project (str, obligatorio): nombre del proyecto
• environment (str, obligatorio): environment (dev, staging, prod, ...)
• bucket (str, opcional): bucket indicado por el usuario — tiene prioridad sobre BACKEND_CONFIG
• region (str, opcional): region indicada por el usuario — tiene prioridad sobre BACKEND_CONFIG

Normalmente resuelve desde la variable de entorno BACKEND_CONFIG (JSON con backends y environment_mapping). Si no está definida, no falla: devuelve needs_user_input con la pregunta que el agente debe hacer, para volver a llamarla con bucket y region.

{
  "needs_user_input": true,
  "missing": ["bucket", "region"],
  "question_for_user": "¿En qué bucket de S3 y en qué region quieres guardar el state?"
}

Desarrollo

# Instala las dependencias de desarrollo
pip install -e ".[dev]"

# Ejecuta en modo desarrollo
python -m terraform_mcp_server.server

Convención de nombres de los módulos

Los módulos siguen el patrón: terraform-aws-module-{service_name}

Ejemplos:

• terraform-aws-module-vpc → service_name: vpc
• terraform-aws-module-ec2 → service_name: ec2
• terraform-aws-module-rds → service_name: rds
• terraform-aws-module-s3 → service_name: s3

Licencia

MIT