CodeSSRockMan/terraform-plan-mcp-server

Terraform Plan Analyzer MCP Server

A Model Context Protocol (MCP) server that provides tools for analyzing Terraform plans. This server can execute terraform commands, analyze plan output, generate reports, and track log files.

Features

• Execute Terraform Commands: Run terraform plan and other commands safely
• Plan Analysis: Parse terraform plan output and extract resource changes
• Report Generation: Create markdown reports with filtered results
• Log File Tracking: Keep track of generated log files
• Configurable Filtering: Filter out specific resource patterns (manifest versions, NAT VMs, etc.)
• Environment Variable Support: Execute commands with custom environment variables

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Ensure you have terraform installed and available in your PATH

Usage

As an MCP Server

Run the server using stdio transport:

python server.py

The server will communicate using the Model Context Protocol over stdin/stdout.

Available Tools

1. run_terraform_plan

Execute a terraform plan command and return the output.

Parameters:

• command (optional): The terraform command to execute (default: "terraform plan")
• working_directory (optional): Directory to run the command in

Example:

{
  "name": "run_terraform_plan",
  "arguments": {
    "command": "terraform plan -out=myplan.tfplan",
    "working_directory": "/path/to/terraform/project"
  }
}

2. analyze_terraform_output

Analyze terraform plan output and extract changes.

Parameters:

• plan_output: The terraform plan output text to analyze
• filter_patterns (optional): List of patterns to filter out from results

Example:

{
  "name": "analyze_terraform_output",
  "arguments": {
    "plan_output": "# terraform plan output here...",
    "filter_patterns": ["temp", "staging"]
  }
}

3. generate_plan_report

Generate a comprehensive markdown report from terraform plan output.

Parameters:

• plan_output: The terraform plan output text to analyze
• output_file (optional): File path to save the report

Example:

{
  "name": "generate_plan_report",
  "arguments": {
    "plan_output": "# terraform plan output here...",
    "output_file": "/path/to/report.md"
  }
}

4. run_custom_terraform_command

Execute a custom terraform command with optional environment variables.

Parameters:

• command: The terraform command to execute
• working_directory (optional): Directory to run the command in
• environment_vars (optional): Environment variables to set

Example:

{
  "name": "run_custom_terraform_command",
  "arguments": {
    "command": "terraform plan -var-file=staging.tfvars",
    "working_directory": "/path/to/project",
    "environment_vars": {
      "TF_WORKSPACE": "staging",
      "TF_LOG": "INFO"
    }
  }
}

Configuration

Filtering Patterns

By default, the analyzer filters out resources containing these patterns:

• manifest
• version
• nat-vm
• nat_vm

You can customize these patterns using the filter_patterns parameter in the analyze_terraform_output tool.

Working Directory

If no working directory is specified, the server will use the current working directory where the server was started.

Integration Examples

With MCP Clients

The server follows the standard MCP protocol and can be integrated with any MCP-compatible client (Claude Desktop, GitHub Copilot CLI, etc.).

Example configuration:

{
  "mcpServers": {
    "terraform-analyzer": {
      "command": "python",
      "args": ["/path/to/terraform-plan-mcp-server/server.py"],
      "cwd": "/path/to/your/terraform/project"
    }
  }
}

Development

Project Structure

terraform-plan-mcp-server/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── examples/              # Usage examples (optional)
└── tests/                 # Unit tests (optional)

Key Components

1. TerraformPlanAnalyzer: Core class for terraform operations
2. MCP Tools: Decorated functions that implement the MCP tool interface
3. Async Operations: All terraform commands run asynchronously
4. Logging: Proper logging to stderr (not stdout) to avoid interfering with MCP protocol

Error Handling

The server includes comprehensive error handling:

• Command execution errors are captured and returned
• Environment variable restoration after custom commands
• Proper cleanup of temporary files
• Logging of errors for debugging

Security Considerations

• The server executes shell commands, so ensure it runs in a secure environment
• Environment variables are properly restored after custom commands
• Log files are created with appropriate permissions
• No sensitive data is logged or exposed

Extending the Server

To add new tools:

1. Define a new function with the @server.tool() decorator
2. Include proper type hints and docstrings
3. Return List[types.TextContent] with the results
4. Handle errors appropriately and log them

Example:

@server.tool()
async def my_custom_tool(param1: str, param2: Optional[int] = None) -> List[types.TextContent]:
    """
    Description of what this tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 (optional)
    """
    try:
        # Tool implementation here
        result = f"Processing {param1} with {param2}"
        return [types.TextContent(type="text", text=result)]
    except Exception as e:
        logger.error(f"Error in my_custom_tool: {e}")
        return [types.TextContent(type="text", text=f"Error: {str(e)}")]

License

This project is provided as-is for educational and development purposes.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues or questions:

1. Check the logs for error messages
2. Verify terraform is properly installed
3. Ensure working directory permissions are correct
4. Check MCP client configuration