Skip to main content
Glama

terraform-mcp-server

MCP (Model Context Protocol) server para gestionar los módulos de Terraform de la organización 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

Related MCP server: GitHub MCP Server

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

Available Tools

5 tools
get_backend_configA

Obtiene la configuración del backend S3 de un proyecto Terraform.

Devuelve el bucket, la key, la region y la configuración de locking correctos según el team, el project y el environment. Normalmente se resuelve desde la variable de entorno BACKEND_CONFIG (string JSON).

Si BACKEND_CONFIG no está definida, esta tool devuelve needs_user_input: pregunta al usuario el bucket y la region y vuelve a llamarla pasando esos valores en bucket y region. Nunca generes el backend comentado ni con placeholders.

Args: team: Nombre del equipo (por ejemplo, 'platform', 'backend', 'data'). project: Nombre del proyecto (por ejemplo, 'onboarding', 'payments'). environment: Environment (por ejemplo, 'dev', 'staging', 'prod'). bucket: Bucket de state indicado por el usuario. Tiene prioridad sobre BACKEND_CONFIG. region: Region del bucket indicada por el usuario. Tiene prioridad sobre BACKEND_CONFIG.

Returns: Objeto JSON con la configuración completa del bloque backend "s3" y el archivo destino (backend.tf).

Inputs: team (required), project (required), environment (required), bucket, +1 more. Returns: result

get_moduleA

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

Recupera el README, variables.tf, outputs.tf y el último tag de versión del módulo identificado por su nombre de servicio.

Args: service_name: Nombre del servicio (por ejemplo, 'vpc', 'ec2'). El nombre del repo se construye como 'terraform-aws-module-{service_name}'.

Returns: Objeto JSON con el detalle del módulo: readme, variables, outputs y última versión.

Inputs: service_name (required). Returns: result

list_module_versionsA

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

Devuelve todos los tags ordenados por versión semántica descendente.

Args: service_name: Nombre del servicio (por ejemplo, 'vpc', 'ec2').

Returns: Objeto JSON con la lista de versiones.

Inputs: service_name (required). Returns: result

scaffold_terraformA

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

Crea la estructura de archivos estándar: versions.tf, providers.tf, variables.tf, terraform.tfvars, main.tf, outputs.tf y data.tf.

El provider generado siempre asume el rol IAM IAC_ROLE_NAME; las credenciales estáticas no son una opción. Rellena aws_account_id en terraform.tfvars.

Args: service_name: Nombre del servicio (por ejemplo, 'vpc', 'ec2'). variables: Dict opcional de valores para precargar en terraform.tfvars.

Returns: Dict JSON con el nombre de archivo como key y su contenido como value.

Inputs: service_name (required), variables. Returns: result

search_modulesA

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

Lista los repos que coinciden con el prefijo 'terraform-aws-module-'. Si se pasa una query, los resultados se filtran además por el nombre del servicio.

Args: query: Filtro opcional para acotar los resultados por nombre de servicio.

Returns: Lista JSON de módulos con name, service_name, description, last_updated y default_branch.

Inputs: query. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: search_modules finds modules, list_module_versions lists versions, get_module retrieves details, scaffold_terraform generates config, and get_backend_config retrieves backend setup. No two tools overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (search_modules, list_module_versions, get_module, scaffold_terraform, get_backend_config). The convention is uniform and predictable.

    Tool Count5/5

    With 5 tools, the server is well-scoped for its purpose of discovering, inspecting, and scaffolding Terraform modules. Each tool serves a clear function without redundancy or overload.

    Completeness4/5

    The surface covers the core lifecycle of module discovery and usage: search, version listing, detail retrieval, scaffolding, and backend config. Missing operations like module creation/update or plan/apply are outside the apparent scope, so the gap is minor.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers