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:

• 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:

1. If you haven't already, install tfmcp:

   cargo install tfmcp
   

   Alternatively, you can use Docker:

   docker build -t tfmcp .
   

2. Find the path to your installed tfmcp executable:

   which tfmcp
   

3. 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"
      }
    }
  }
}

4. Restart Claude Desktop and enable the tfmcp tool.

5. 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_APPR