Connected Terraform Module

Connected Terraform Module is an MCP server that brings HashiCorp Terraform infrastructure management capabilities to AI assistants, enabling conversational interaction with Terraform configurations, state files, plan outputs, and module registries. This MCP bridge allows language models to generate Terraform HCL code, inspect infrastructure state, analyze plan diffs, and navigate the Terraform module ecosystem through natural language.

When to Use This MCP Server

Connect this server when...

• You are writing Terraform configurations and want AI assistance generating HCL resource blocks and module references
• Your team manages infrastructure with Terraform and you need conversational access to state files and plan outputs
• You want to analyze Terraform plan diffs to understand what infrastructure changes a deployment will introduce
• You need to search the Terraform Registry for modules and providers that match your infrastructure requirements
• You are troubleshooting Terraform errors and want AI-guided analysis of state conflicts and dependency issues

Consider alternatives when...

• Your infrastructure uses Pulumi, CloudFormation, or CDK exclusively without Terraform involvement
• You only need to provision a single cloud resource without ongoing state management
• You require real-time infrastructure monitoring rather than IaC development tools

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "terraform": {
      "command": "npx",
      "args": ["-y", "@hashicorp/terraform-mcp-server"],
      "env": {
        "TF_TOKEN": "your-terraform-cloud-token"
      }
    }
  }
}

Connection setup:

1. Install Terraform CLI from terraform.io/downloads
2. For Terraform Cloud integration, generate an API token at app.terraform.io > User Settings > Tokens
3. Add the configuration above to your .mcp.json file
4. Restart your MCP client to activate the Terraform server

Example tool usage:

# Generate Terraform code
> Create a Terraform configuration for an AWS EC2 instance with a security group allowing SSH

# Inspect state
> Show me all resources in the current Terraform state and their provider types

# Analyze a plan
> What changes will be applied if I run terraform apply on this configuration?

Core Concepts

Concept	Purpose	Details
HCL Configuration	Infrastructure definition	HashiCorp Configuration Language files (.tf) that declare the desired state of cloud resources
State File	Resource tracking	JSON document that maps Terraform-managed resources to their real-world cloud counterparts
Plan Output	Change preview	Detailed diff showing resources that will be created, updated, or destroyed on the next apply
Modules	Reusable components	Packaged Terraform configurations shared through the Terraform Registry for common infrastructure patterns
Providers	Cloud adapters	Plugins that connect Terraform to specific cloud platforms (AWS, Azure, GCP) and services

Architecture:

+------------------+       +------------------+       +------------------+
|  Terraform       |       |  Terraform MCP   |       |  AI Assistant    |
|  CLI + Cloud     |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  State/Registry  | API   |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+------------------------------------------------------+
|  Workspaces > State > Plans > Modules > Providers     |
+------------------------------------------------------+

Configuration

Parameter	Type	Default	Description
TF_TOKEN	string	none	Terraform Cloud API token for accessing remote workspaces and state
TF_WORKSPACE	string	default	Default Terraform Cloud workspace for state and plan operations
terraform_path	string	terraform	Path to the Terraform CLI binary if not in the system PATH
registry_url	string	https://registry.terraform.io	Terraform Registry URL for module and provider searches
state_path	string	./terraform.tfstate	Path to local state file when not using Terraform Cloud

Best Practices

1. Use Terraform Cloud for shared state access. Configure the MCP server with a Terraform Cloud token to access remote state files shared across your team. Local state files are single-user and can become out of date. Remote state ensures the AI sees the same infrastructure truth as your team.

2. Always review plan output before apply suggestions. When the AI generates Terraform code or suggests changes, always request a plan output first. The plan shows exactly what will change, be created, or be destroyed. Never proceed directly to apply without reviewing the plan, especially for production environments.

3. Leverage module search for common patterns. Before writing custom Terraform from scratch, ask the AI to search the Terraform Registry for existing modules. Well-maintained community modules save development time and encode best practices for common infrastructure patterns.

4. Pin provider and module versions. When the AI generates Terraform configurations, ensure provider and module version constraints are included. Unpinned versions can introduce breaking changes when providers update. Use the ~> operator for minor version flexibility while preventing major version jumps.

5. Separate state by environment and responsibility. Organize your Terraform workspaces so that production, staging, and development infrastructure have separate state files. This isolation prevents accidental modifications to production resources when the AI is working with development configurations.

Common Issues

"Backend initialization required" error. The Terraform MCP server may need an initialized backend to access state. Run terraform init in the working directory before connecting the MCP server. For Terraform Cloud backends, ensure the TF_TOKEN environment variable is set with a valid token.

State file shows resources that no longer exist. This indicates state drift where cloud resources were modified or deleted outside of Terraform. Ask the AI to inspect the state for discrepancies and suggest running terraform refresh to synchronize the state with actual cloud resources.

Module search returns no results. The Terraform Registry search requires specific keywords that match module names and descriptions. Try broader search terms or browse by provider. If you are searching for private modules, ensure the registry URL points to your private registry.