mjrestivo16/mcp-terraform

Terraform MCP Server

Model Context Protocol (MCP) server for Terraform Infrastructure as Code operations. Provides 25 comprehensive tools for managing Terraform configurations, state, workspaces, and executing infrastructure operations.

Features

Core Operations (6 tools)

• tf_version - Get Terraform version information
• tf_init - Initialize Terraform working directory (with optional provider upgrades)
• tf_validate - Validate Terraform configuration syntax
• tf_plan - Create execution plan showing proposed changes
• tf_apply - Apply Terraform changes to infrastructure
• tf_destroy - Destroy Terraform-managed infrastructure

Output Management (1 tool)

• tf_output - Get Terraform output values (JSON or plain text)

State Management (6 tools)

• tf_state_list - List all resources in Terraform state
• tf_state_show - Show detailed information for a specific resource
• tf_state_rm - Remove a resource from Terraform state
• tf_state_mv - Move/rename a resource in Terraform state
• tf_import - Import existing infrastructure into Terraform state
• tf_refresh - Refresh Terraform state from real infrastructure

Code Formatting (1 tool)

• tf_fmt - Format Terraform configuration files (check or modify)

Workspace Management (4 tools)

• tf_workspace_list - List all Terraform workspaces
• tf_workspace_select - Switch to a different workspace
• tf_workspace_new - Create a new workspace
• tf_workspace_delete - Delete a workspace

Provider Management (1 tool)

• tf_providers - List Terraform providers in use

Advanced Operations (3 tools)

• tf_graph - Generate resource dependency graph in DOT format
• tf_taint - Mark a resource for recreation on next apply
• tf_untaint - Remove taint marking from a resource

Plan Management (1 tool)

• tf_show_plan - Show details of a saved execution plan file

File Operations (3 tools)

• tf_list_files - List Terraform files in a directory (.tf, .tfvars, .tfstate)
• tf_read_file - Read contents of a Terraform configuration file
• tf_write_file - Write content to a Terraform configuration file

Installation

npm install
npm run build

Configuration

The server uses an optional environment variable to set the default working directory:

export TERRAFORM_WORKING_DIR="/path/to/your/terraform/projects"

If not set, the server will use the current working directory.

Usage with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Development

Run in development mode with hot reload:

npm run dev

Requirements

• Terraform CLI must be installed and available in your PATH
• Appropriate cloud provider credentials configured (AWS, Azure, GCP, etc.)
• Terraform working directory with configuration files

Example Use Cases

1. Infrastructure Planning: Review changes before applying them
2. State Management: Import existing resources, move resources between modules
3. Workspace Management: Manage multiple environments (dev, staging, prod)
4. Code Quality: Format Terraform files consistently
5. Troubleshooting: Inspect state, visualize resource dependencies
6. Selective Operations: Apply changes to specific resources using targets
7. Configuration Management: Read and modify Terraform configuration files

Tool Parameters

Common Parameters

• dir (optional): Working directory for Terraform operations. Defaults to TERRAFORM_WORKING_DIR or current directory
• auto_approve (optional): Skip interactive approval for apply/destroy operations
• target (optional): Limit operations to specific resources (e.g., aws_instance.example)
• var (optional): Pass variables to Terraform commands (object with key-value pairs)

Plan Operations

{
  "dir": "/path/to/project",
  "out": "plan.tfplan",
  "target": "aws_instance.web",
  "var": {
    "region": "us-west-2",
    "instance_type": "t3.micro"
  }
}

State Operations

{
  "dir": "/path/to/project",
  "address": "aws_instance.example",
  "source": "aws_instance.old_name",
  "destination": "aws_instance.new_name"
}

Security Considerations

• The server executes Terraform commands with full permissions
• Ensure proper access controls on the working directory
• Be cautious with auto_approve flag on apply/destroy operations
• Store sensitive variables in Terraform variable files or environment variables, not in plain text
• Review plans carefully before applying changes to production infrastructure

Output Formats

• Most commands return plain text output from Terraform CLI
• Use json: true with tf_output for structured JSON responses
• State operations return formatted resource information
• Graph operations return DOT format for visualization tools

Visualization

The tf_graph tool generates dependency graphs in DOT format. Use tools like Graphviz to visualize:

# Save graph output to file
terraform graph > graph.dot

# Generate PNG image
dot -Tpng graph.dot -o graph.png

Error Handling

The server captures both stdout and stderr from Terraform commands. Failed operations return error messages with exit codes for troubleshooting.

API Reference

For detailed Terraform CLI documentation, see: https://developer.hashicorp.com/terraform/cli

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.