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 runs local Terraform workflows through the Model Context Protocol (MCP). It helps AI assistants inspect a project, prepare execution, review a saved plan, apply that same plan, and check the result. Registry and HCP/TFE tools support these local workflows.

🎮 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

🎉 Current Release

tfmcp v0.2.3 is the current release:

cargo install tfmcp --version 0.2.3

What's new in v0.2.3

• Saved plans shared by analysis, review, PR summaries, and apply
• Local execution preparation with workspace, backend, validation, and state checks
• Correct Terraform JSON parsing and sensitive-value redaction
• Non-interactive execution, timeouts, and structured apply/state verification
• RMCP 3.1.2 and updated Rust tooling with the Rust 1.88 MSRV retained

Features

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 1.88.0+ (Rust Edition 2024)
• Terraform CLI 1.15.8 installed and available in PATH
• An MCP-compatible AI client (for example, Claude Desktop or Codex)
• 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:

   bash

   Copy

   cargo install tfmcp
   

   Alternatively, you can use Docker:

   Terminal

   Copy

   docker build -t tfmcp .
   

2. Find the path to your installed tfmcp executable:

   bash

   Copy

   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.

Local plan/apply workflow

Start with tfmcp --dir /path/to/project mcp --toolsets terraform. The default toolset supports preparation and plan review; the terraform toolset also exposes initialization and gated local writes.

1. Call prepare_terraform_change to inspect the selected directory, Terraform version, workspace, backend, configuration validity, and state readability. ready means the inspected prerequisites passed; input variables and provider credentials are checked by the actual plan. Initialize with init_terraform when required, then repeat preparation.
2. Call get_terraform_plan with {} or, for example, {"var_files":["environment.tfvars"]}. The result includes a plan_id, target, created_at, has_changes, and a redacted Terraform JSON plan string. Use replace for resource replacement addresses or refresh_only:true to preview drift without modifying state.
3. Pass the returned plan_id to analyze_plan, review_terraform_plan, and summarize_plan_for_pr. These calls reuse the saved result. Omitting the ID creates a new plan. A review decision is advisory and does not authorize apply.
4. After reviewing and approving the change, call apply_terraform with {"plan_id":"<returned ID>","auto_approve":true}. Both TFMCP_ALLOW_DANGEROUS_OPS=true and TFMCP_ALLOW_AUTO_APPROVE=true must already be configured on the server. The saved plan determines the applied changes, including when configuration files have subsequently been edited.
5. Check success, exit_code, diagnostics, and state_verified in the apply result. Retrieve the plan's final status with get_terraform_plan({"plan_id":"<returned ID>"}). After failure or timeout, inspect state and create a new plan; the attempted ID cannot be applied again.

Migration from v0.2.2: apply_terraform requires plan_id; calls that only provide auto_approve now return an explanatory error. Approval happens in the client before the call, because Terraform receives no interactive input.

Saved plans use private temporary directories and are bound to the project, workspace, initialized backend metadata, Terraform version, and provider lockfile. Plan IDs remain valid only for the current server process, with a maximum of 64 retained plans. Normal server shutdown removes the temporary files. outcome_unknown means an interrupted attempt has no confirmed result; inspect state before continuing. Status retrieval waits for an ongoing operation to finish; live progress and restart recovery are not provided in this release.

MCP Tools

tfmcp provides 82 MCP tools for AI assistants:

Core Terraform Operations