Terraform Docs MCP: AI-Powered Infrastructure Generation

Amaresh Pelleti

Introduction

Infrastructure as Code (IaC) has revolutionized how we manage cloud resources, with Terraform leading the charge. However, maintaining documentation and generating proper configurations can be challenging, especially for teams just getting started with Terraform. Today, I’m excited to introduce terraform-docs-mcp, a tool that leverages the Model Context Protocol (MCP) to help you generate Terraform documentation and configurations directly through your AI assistant.

What is Model Context Protocol (MCP)?

Before diving into our project, let’s briefly explain what MCP is. The Model Context Protocol allows AI models to interact with tools and services through a standardized interface. Think of it as a bridge that enables AI assistants like Claude to access external capabilities – in our case, Terraform documentation and configuration generation.

Instead of relying on the AI model’s training data (which might be outdated or incomplete), MCP provides real-time access to specific functions that can retrieve or generate information.

The terraform-docs-mcp Project

Our terraform-docs-mcp project provides a Node.js-based MCP server that exposes Terraform capabilities to any compatible AI assistant. It’s designed to be lightweight, user-friendly, and easily extendable.

Key Features

The tool currently offers three main capabilities:

  1. Provider Documentation Retrieval – Fetch up-to-date documentation for Terraform providers and resources
  2. Configuration Generation – Create Terraform configuration files based on provider and resource specifications
  3. Resource Schema Exploration – Examine the attributes and properties available for specific Terraform resources

Technical Architecture

The project is built using TypeScript and leverages the official MCP SDK. Here’s a high-level view of how it works:

┌─────────────┐     ┌─────────────────┐     ┌───────────────────┐
│ AI Assistant│─────┤ MCP Protocol    │─────┤ terraform-docs-mcp │
│ (e.g. Claude)│     │ Communication   │     │ Server             │
└─────────────┘     └─────────────────┘     └───────────────────┘
                                                     │
                                                     ▼
                                            ┌───────────────────┐
                                            │ Terraform Registry │
                                            │ & Documentation    │
                                            └───────────────────┘

When a user asks their AI assistant about Terraform resources or configurations, the assistant can use the MCP server to fetch accurate, up-to-date information or generate proper configuration examples.

Getting Started

Let’s walk through how to set up and use terraform-docs-mcp with your AI assistant.

Installation

# Clone the repository
git clone https://github.com/littleworks-inc/terraform-docs-mcp.git
cd terraform-docs-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Configuration

The server is configured to run as a command-line tool that communicates via stdin/stdout, making it compatible with various MCP client implementations. The claude_desktop_config.json file shows an example of how to configure Claude Desktop to use the tool.

{
  "mcpServers": {
    "terraform-docs": {
      "command": "node",
      "args": [
        "/path/to/terraform-docs-mcp/dist/index.js"
      ]
    }
  }
}

Use Cases

Let’s explore some practical use cases for terraform-docs-mcp:

1. Learning Terraform Resources

Imagine you’re new to Terraform and trying to understand how to create an AWS S3 bucket. Instead of jumping between documentation pages, you can simply ask your AI assistant:

“Can you show me the documentation and an example for creating an S3 bucket in Terraform?”

The assistant will use terraform-docs-mcp to fetch the latest documentation and examples, ensuring you get accurate information.

2. Generating Configuration Templates

When starting a new Terraform project, you might want a template to build upon. Simply ask:

“Generate a Terraform configuration for an AWS EC2 instance with tags for production environment”

The assistant will use the tool to create a properly formatted configuration file with the appropriate attributes.

3. Exploring Resource Options

Understanding available attributes for complex resources can be challenging. With terraform-docs-mcp, you can ask:

“What attributes are available for an Azure Kubernetes Service cluster?”

The assistant will fetch the schema and present you with a comprehensive list of options.

How It Works: Under the Hood

At its core, terraform-docs-mcp consists of three main components:

  1. Server Implementation – The core MCP server that handles tool registration and requests
  2. Documentation Fetcher – A module that retrieves documentation from the Terraform Registry
  3. Configuration Generator – A module that transforms schema and attributes into valid Terraform configurations

The tool uses the official MCP SDK to establish a communication channel with AI assistants. When a request comes in, it routes it to the appropriate handler based on the requested capability.

Let’s take a look at the core logic for generating Terraform configurations:

async function generateTerraformConfiguration(args: GenerateConfigArgs) {
  const { provider, resource, attributes = {} } = args;
  
  try {
    // First, get the resource schema
    const schemaResponse = await fetchResourceSchema({ provider, resource });
    
    if (schemaResponse.error) {
      return schemaResponse;
    }
    
    const schema = schemaResponse.result;
    
    // Generate Terraform configuration using the schema and provided attributes
    const configuration = generateTerraformConfig(provider, resource, schema, attributes);
    
    return {
      result: configuration
    };
  } catch (error: any) {
    return {
      error: {
        message: `Failed to generate Terraform configuration: ${error.message}`
      }
    };
  }
}

This function first retrieves the schema for the requested resource, then uses that schema to generate a properly formatted Terraform configuration file.

Extending the Project

One of the strengths of terraform-docs-mcp is its extensibility. Here are some ways you could enhance the project:

  1. Provider Coverage – Add support for more Terraform providers beyond AWS, GCP, and Azure
  2. Module Generation – Extend the tool to generate reusable Terraform modules
  3. State Management – Add capabilities to help with state file management and migration
  4. Integration Tests – Validate generated configurations against real cloud providers
  5. Web UI – Create a web-based interface for non-CLI usage

Best Practices for Terraform with AI Assistance

When using AI assistants with terraform-docs-mcp, keep these best practices in mind:

  1. Validate Generated Code – Always review and test configurations before applying them
  2. Be Specific – Provide detailed requirements when requesting configurations
  3. Understand the Basics – Learn Terraform fundamentals to ask better questions
  4. Iterate – Use the tool to generate a starting point, then refine as needed
  5. Security First – Don’t include sensitive information in your requests

Conclusion

Terraform has transformed infrastructure management, but the learning curve and documentation challenges remain. With terraform-docs-mcp, we’re bridging the gap between natural language interaction and technical implementation, making Terraform more accessible to teams of all experience levels.

By leveraging the Model Context Protocol, we’re demonstrating how AI assistants can move beyond their training data to provide real-time, accurate technical guidance. The project is open source and we welcome contributions to expand its capabilities.

Whether you’re a Terraform novice looking for guidance or an experienced practitioner seeking efficiency, terraform-docs-mcp can help streamline your infrastructure as code journey.

Resources

Have you tried using AI assistants for infrastructure as code? What challenges have you faced with Terraform documentation? Let us know in the comments below!

Leave a Reply