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
- Install dependencies:
pip install -r requirements.txt
- 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 analyzefilter_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 analyzeoutput_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 executeworking_directory(optional): Directory to run the command inenvironment_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:
manifestversionnat-vmnat_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
- TerraformPlanAnalyzer: Core class for terraform operations
- MCP Tools: Decorated functions that implement the MCP tool interface
- Async Operations: All terraform commands run asynchronously
- 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:
- Define a new function with the
@server.tool()decorator - Include proper type hints and docstrings
- Return
List[types.TextContent]with the results - 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Support
For issues or questions:
- Check the logs for error messages
- Verify terraform is properly installed
- Ensure working directory permissions are correct
- Check MCP client configuration