# 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
```bash
npm install
npm run build
```
## Configuration
The server uses an optional environment variable to set the default working directory:
```bash
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`
```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:
```bash
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
```json
{
"dir": "/path/to/project",
"out": "plan.tfplan",
"target": "aws_instance.web",
"var": {
"region": "us-west-2",
"instance_type": "t3.micro"
}
}
```
### State Operations
```json
{
"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:
```bash
# 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.
