tfmcp: Terraform Model Context Protocol Tool by nwiizo - MCP Server

tfmcp: Terraform Model Context Protocol Tool

⚠️ This project includes production-ready security features but is still under active development. While the security system provides robust protection, please review all operations carefully in production environments. ⚠️

tfmcp is a command-line tool that helps you interact with Terraform via the Model Context Protocol (MCP). It allows LLMs to manage and operate your Terraform environments, including:

🎮 Demo

See tfmcp in action with Claude Desktop:

tfmcp Demo with Claude Desktop

Reading Terraform configuration files
Analyzing Terraform plan outputs
Applying Terraform configurations
Managing Terraform state
Creating and modifying Terraform configurations

🎉 Latest Release

The latest version of tfmcp (v0.1.9) is now available on Crates.io! You can easily install it using Cargo:

cargo install tfmcp

🆕 What's New in v0.1.9

📊 Plan Analysis: Structured plan analysis with risk scoring and recommendations
🔍 State Analysis: Deep state inspection with drift detection
📁 Workspace Management: Full terraform workspace support (list, show, new, select, delete)
📥 Import Helper: Guided resource import with config generation
✨ Code Formatting: terraform fmt integration
🔗 Dependency Graph: terraform graph visualization with DOT output
📤 Output Management: terraform output access
🏷️ Taint/Untaint: Resource taint management (with deprecation notices for 1.5+)
🔄 State Refresh: Explicit state refresh operations
📦 Provider Info: Detailed provider information with lock file parsing
🦀 Rust Edition 2024: Migrated to Rust Edition 2024 (requires Rust 1.85.0+)

Features

🚀 Terraform Integration Deeply integrates with the Terraform CLI to analyze and execute operations.
📄 MCP Server Capabilities Runs as a Model Context Protocol server, allowing AI assistants to access and manage Terraform.
🔬 Module Health Analysis Whitebox approach to Infrastructure as Code with cohesion/coupling analysis, health scoring, and refactoring suggestions based on software engineering principles.
📊 Resource Dependency Graph Visualize resource relationships including explicit depends_on and implicit reference dependencies.
📦 Module Registry Integration Search and explore Terraform modules from the registry, get module details and versions.
🔐 Enterprise Security Production-ready security controls with configurable policies, audit logging, and access restrictions.
📊 Advanced Analysis Detailed Terraform configuration analysis with best practice recommendations and security checks.
📋 Guideline Compliance (v0.1.8) Future Architect Terraform guidelines integration with compliance scoring, secret detection, and variable quality checks.
⚡️ Blazing Fast High-speed processing powered by the Rust ecosystem with optimized parsing and caching.
🛠️ Automatic Setup Automatically creates sample Terraform projects when needed, ensuring smooth operation even for new users.
🐳 Docker Support Run tfmcp in a containerized environment with all dependencies pre-installed.

Installation

From Source

# Clone the repository
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

# Build and install
cargo install --path .

From Crates.io

cargo install tfmcp

Using Docker

# Clone the repository
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

# Build the Docker image
docker build -t tfmcp .

# Run the container
docker run -it tfmcp

Requirements

Rust (edition 2021)
Terraform CLI installed and available in PATH
Claude Desktop (for AI assistant integration)
Docker (optional, for containerized deployment)

Usage

$ tfmcp --help
✨ A CLI tool to manage Terraform configurations and operate Terraform through the Model Context Protocol (MCP).

Usage: tfmcp [OPTIONS] [COMMAND]

Commands:
  mcp       Launch tfmcp as an MCP server
  analyze   Analyze Terraform configurations
  help      Print this message or the help of the given subcommand(s)

Options:
  -c, --config <PATH>    Path to the configuration file
  -d, --dir <PATH>       Terraform project directory
  -V, --version          Print version
  -h, --help             Print help

Using Docker

When using Docker, you can run tfmcp commands like this:

# Run as MCP server (default)
docker run -it tfmcp

# Run with specific command and options
docker run -it tfmcp analyze --dir /app/example

# Mount your Terraform project directory
docker run -it -v /path/to/your/terraform:/app/terraform tfmcp --dir /app/terraform

# Set environment variables
docker run -it -e TFMCP_LOG_LEVEL=debug tfmcp

Integrating with Claude Desktop

To use tfmcp with Claude Desktop:

If you haven't already, install tfmcp:
```
cargo install tfmcp
```
Alternatively, you can use Docker:
```
docker build -t tfmcp .
```
Find the path to your installed tfmcp executable:
```
which tfmcp
```
Add the following configuration to ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tfmcp": {
      "command": "/path/to/your/tfmcp",  // Replace with the actual path from step 2
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/yourusername",  // Replace with your username
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "TERRAFORM_DIR": "/path/to/your/terraform/project"  // Optional: specify your Terraform project
      }
    }
  }
}

If you're using Docker with Claude Desktop, you can set up the configuration like this:

{
  "mcpServers": {
    "tfmcp": {
      "command": "docker",
      "args": ["run", "--rm", "-v", "/path/to/your/terraform:/app/terraform", "tfmcp", "mcp"],
      "env": {
        "TERRAFORM_DIR": "/app/terraform"
      }
    }
  }
}

Restart Claude Desktop and enable the tfmcp tool.
tfmcp will automatically create a sample Terraform project in ~/terraform if one doesn't exist, ensuring Claude can start working with Terraform right away. The sample project is based on the examples included in the example/demo directory of this repository.

MCP Tools

tfmcp provides 31 MCP tools for AI assistants:

Core Terraform Operations

Tool	Description
`init_terraform`	Initialize Terraform working directory
`get_terraform_plan`	Generate and show execution plan
`analyze_plan`	NEW Analyze plan with risk scoring and recommendations
`apply_terraform`	Apply Terraform configuration
`destroy_terraform`	Destroy Terraform-managed infrastructure
`validate_terraform`	Validate configuration syntax
`validate_terraform_detailed`	Detailed validation with guidelines
`get_terraform_state`	Show current state
`analyze_state`	NEW Analyze state with drift detection
`list_terraform_resources`	List all managed resources
`set_terraform_directory`	Change active project directory

Workspace & State (v0.1.9)

Tool	Description
`terraform_workspace`	NEW Manage workspaces (list, show, new, select, delete)
`terraform_import`	NEW Import existing resources
`terraform_taint`	NEW Taint/untaint resources
`terraform_refresh`	NEW Refresh state

Code & Output (v0.1.9)

Tool	Description
`terraform_fmt`	NEW Format code
`terraform_graph`	NEW Generate dependency graph
`terraform_output`	NEW Get output values
`terraform_providers`	NEW Get provider info with lock file

Analysis & Security

Tool	Description
`analyze_terraform`	Analyze configuration
`analyze_module_health`	Module health with cohesion/coupling metrics
`get_resource_dependency_graph`	Resource dependencies visualization
`suggest_module_refactoring`	Refactoring suggestions
`get_security_status`	Security scan with secret detection

Registry

Tool	Description
`search_terraform_providers`	Search providers
`get_provider_info`	Provider details
`get_provider_docs`	Provider documentation
`search_terraform_modules`	Search modules
`get_module_details`	Module details
`get_latest_module_version`	Latest module version
`get_latest_provider_version`	Latest provider version

Logs and Troubleshooting

The tfmcp server logs are available at:

~/Library/Logs/Claude/mcp-server-tfmcp.log

Common issues and solutions:

Claude can't connect to the server: Make sure the path to the tfmcp executable is correct in your configuration
Terraform project issues: tfmcp automatically creates a sample Terraform project if none is found
Method not found errors: MCP protocol support includes resources/list and prompts/list methods
Docker issues: If using Docker, ensure your container has proper volume mounts and permissions

Environment Variables

Core Configuration

TERRAFORM_DIR: Set this to specify a custom Terraform project directory. If not set, tfmcp will use the directory provided by command line arguments, configuration files, or fall back to ~/terraform. You can also change the project directory at runtime using the set_terraform_directory tool.
TFMCP_LOG_LEVEL: Set to debug, info, warn, or error to control logging verbosity.
TFMCP_DEMO_MODE: Set to true to enable demo mode with additional safety features.

Security Configuration

TFMCP_ALLOW_DANGEROUS_OPS: Set to true to enable apply/destroy operations (default: false)
TFMCP_ALLOW_AUTO_APPROVE: Set to true to enable auto-approve for dangerous operations (default: false)
TFMCP_MAX_RESOURCES: Set maximum number of resources that can be managed (default: 50)
TFMCP_AUDIT_ENABLED: Set to false to disable audit logging (default: true)
TFMCP_AUDIT_LOG_FILE: Custom path for audit log file (default: ~/.tfmcp/audit.log)
TFMCP_AUDIT_LOG_SENSITIVE: Set to true to include sensitive information in audit logs (default: false)

Security Considerations

tfmcp includes comprehensive security features designed for production use:

🔒 Built-in Security Features

Access Controls: Automatic blocking of production/sensitive file patterns
Operation Restrictions: Dangerous operations (apply/destroy) disabled by default
Resource Limits: Configurable maximum resource count protection
Audit Logging: Complete operation tracking with timestamps and user identification
Directory Validation: Security policy enforcement for project directories

🛡️ Security Best Practices

Default Safety: Apply/destroy operations are disabled by default - explicitly enable only when needed
Review Plans: Always review Terraform plans before applying, especially AI-generated ones
IAM Boundaries: Use appropriate IAM permissions and role boundaries in cloud environments
Audit Monitoring: Regularly review audit logs at ~/.tfmcp/audit.log
File Patterns: Built-in protection against accessing prod*, production*, and secret* patterns
Docker Security: When using containers, carefully consider volume mounts and exposed data

⚙️ Production Configuration

# Recommended production settings
export TFMCP_ALLOW_DANGEROUS_OPS=false    # Keep disabled for safety
export TFMCP_ALLOW_AUTO_APPROVE=false     # Require manual approval
export TFMCP_MAX_RESOURCES=10             # Limit resource scope
export TFMCP_AUDIT_ENABLED=true           # Enable audit logging
export TFMCP_AUDIT_LOG_SENSITIVE=false    # Don't log sensitive data

Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)

Run quality checks before committing:

cargo fmt --all
cargo clippy --all-targets --all-features
cargo test --all-features

Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Release Process

Releases are done manually (automated CI release is disabled):

Update version in Cargo.toml
Create GitHub release: gh release create v0.1.x --title "v0.1.x - Title" --notes "Release notes"
Publish to crates.io: cargo publish

Roadmap

Here are some planned improvements and future features for tfmcp:

Completed

In Progress

Multi-Environment Support Add support for managing multiple Terraform environments, workspaces, and modules.

Planned

Expanded MCP Protocol Support Implement additional MCP methods and capabilities for richer integration with AI assistants.
Performance Optimization
Optimize resource usage and response times for large Terraform projects.
Cost Estimation
Integrate with cloud provider pricing APIs to provide cost estimates for Terraform plans.
Interactive TUI
Develop a terminal-based user interface for easier local usage and debugging.
Integration with Other AI Platforms
Extend beyond Claude to support other AI assistants and platforms.
Plugin System
Develop a plugin architecture to allow extensions of core functionality.