tfmcp is an experimental CLI tool based on the Model Context Protocol (MCP), designed to let AI assistants manage and operate Terraform environments. Through local Terraform workflows, it helps AI assistants inspect projects, prepare execution, review saved plans, apply those plans, and inspect the results. Registry and HCP/TFE tools support these local workflows.
Main capabilities:
- Read Terraform configuration files
- Analyze Terraform plan output
- Apply Terraform configuration
- Manage Terraform state
- Create and modify Terraform configuration
New features in the current version v0.2.4 include: reviewing destroy plans with the same saved plans and permission checks as apply; listing and discarding saved plans to reclaim the 64-plan capacity; retaining apply results, failed/unknown results, and recovery guidance; sensitive output redaction for full and named output queries; upgrading to RMCP 3.5.0, updating dependencies and images, and retaining Rust 1.88 MSRV.
Usage: Users need to install Rust 1.88.0+ (Rust Edition 2024) and Terraform CLI 1.15.8, and ensure they are available in PATH. An MCP-compatible AI client (such as Claude Desktop or Codex) is also required, and Docker is optional. Installation can be done via cargo install tfmcp, or by building an image with Docker: docker build -t tfmcp .
Integration with Claude Desktop: Find the path to the tfmcp executable (which tfmcp), add the configuration in ~/Library/Application Support/Claude/claude_desktop_config.json, restart Claude Desktop, and enable the tfmcp tool. tfmcp automatically creates a sample Terraform project in ~/terraform (if it does not exist), ensuring that Claude can immediately start using Terraform.
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 controlled local writes. Call prepare_terraform_change to check the selected directory, Terraform version, workspace, backend, configuration validity, and state readability. If necessary, initialize with init_terraform, then repeat preparation. Call get_terraform_plan to obtain a plan; the result includes plan_id, target, created_at, has_changes, and a redacted Terraform JSON plan string. Pass the returned plan_id to analyze_plan, review_terraform_plan, and summarize_plan_for_pr. After review approval, call apply_terraform with the plan_id and auto_approve:true, and the server must also have TFMCP_ALLOW_DANGEROUS_OPS=true and TFMCP_ALLOW_AUTO_APPROVE=true configured. Check the apply result for success, status, exit_code, diagnostics, state_verified, and recovery.next_steps. After a failure or timeout, inspect the state and create a new plan; an attempted ID cannot be applied again.
Migration from v0.2.2: apply_terraform requires plan_id; calls that provide only auto_approve now return an explanatory error. Approval happens on the client before the call, because Terraform does not receive interactive input.
For a reviewed destroy: create a plan using get_terraform_plan({"destroy":true}), review its plan_id, then call destroy_terraform with that ID and auto_approve:true. The server must also set TFMCP_DELETE_ENABLED=true, along with the two apply permissions. Set the destroy planPassing to apply_terraform executes the same permissions. destroy cannot be combined with refresh_only or replace. Migrating from v0.2.3: destroy_terraform now requires a saved destroy plan; it no longer creates an unreviewed plan or waits for a prompt.
Use list_terraform_plans to find retained IDs along with their targets and status. Use discard_terraform_plan({"plan_id":"<ID>"}) to delete the temporary files of unneeded plans and free up capacity. Discarding does not change infrastructure, cancel operations, or roll back an apply; check for failed or unknown results before removing the record. These tools are available in the default and Terraform toolsets.
Saved plans use a private temporary directory and are bound to the project, workspace, initialized backend metadata, Terraform version, and provider lock file. Plan IDs are valid only within the current server process, and at most 64 plans are retained. A normal server shutdown deletes the temporary files. failed means Terraform returned a non-zero exit code, and partial changes may have been applied. outcome_unknown means no definitive exit result was obtained, including timeout or cancellation. Both prevent reapplying the same plan and include recovery guidance: confirm the operation has stopped, check the recorded targets and actual resources, resolve the cause, then generate and review a new plan. No rollback or automatic retry is performed. When a request is cancelled before the result can be retained, apply_result is null. State verification checks resource addresses, not all attribute values or output values. State retrieval waits for in-progress operations to complete; this version does not provide real-time progress or restart recovery.
tfmcp provides AI assistants with the following MCP tools: core Terraform operations, workspaces and state (v0.1.9), code and outputs (v0.1.9), analysis and security, HCP Terraform / Terraform Enterprise (read-only), HCP Terraform / Terraform Enterprise (controlled operations), logs, and troubleshooting.
Logs are located at ~/.tfmcp/audit.log. Common issues: Claude cannot connect to the server (ensure the tfmcp executable path in the configuration is correct); Terraform item issues (tfmcp automatically creates a sample project); method not found errors (tfmcp declares and implements tools/list, resources/list, resources/templates/list, and resources/read); Docker issues (ensure the container has the correct volume mounts and permissions).
Environment variables include core configuration (TERRAFORM_DIR, TFMCP_LOG_LEVEL, TFMCP_DEMO_MODE, TFMCP_COMMAND_TIMEOUT_SECONDS), security configuration (ENABLE_TF_OPERATIONS, TFMCP_ALLOW_DANGEROUS_OPS, TFMCP_DELETE_ENABLED, TFMCP_ALLOW_AUTO_APPROVE, TFMCP_MAX_RESOURCES, TFMCP_AUDIT_ENABLED, TFMCP_AUDIT_LOG_FILE, TFMCP_AUDIT_LOG_SENSITIVE), HCP Terraform / Terraform Enterprise (TFE_ADDRESS, TFE_TOKEN, TFE_SKIP_TLS_VERIFY, TFE_MAX_RESPONSE_BYTES), and transport configuration (TRANSPORT_MODE, TRANSPORT_HOST, TRANSPORT_PORT, MCP_ENDPOINT, MCP_HEALTH_ENDPOINT, MCP_METRICS_ENDPOINT, MCP_SESSION_MODE, MCP_HEARTBEAT_INTERVAL, MCP_CORS_MODE, MCP_ALLOWED_ORIGINS, MCP_ALLOWED_HOSTS, MCP_ORGANIZATION_ALLOWLIST, MCP_RATE_LIMIT_GLOBAL, MCP_RATE_LIMIT_SESSION, MCP_TLS_CERT_FILE, MCP_TLS_KEY_FILE).
Security considerations: tfmcp includes comprehensive production-oriented security features, such as access control (automatically blocking production/sensitive file patterns), operation restrictions (dangerous operations disabled by default), resource limits, audit logging, and directory validation.Best practices include secure by default, review plans, IAM boundaries, audit monitoring, file mode protection, and Docker security.
Contribution guidelines: PRs are welcome. Fork the repository, create a feature branch, enable the repository-managed fast pre-commit checks (git config core.hooksPath .githooks), run the full correctness checks (cargo fmt --all -- --check, cargo clippy --all-targets --all-features -- -D warnings, cargo test --locked --all-targets --all-features), commit changes, push the branch, and open a PR. The pre-commit hook always checks staged whitespace and conditionally runs cargo fmt, actionlint, Registry metadata validation, module coupling, and duplicate code checks on affected files. Optional architecture tools remain mandatory in Release.sh; install cargo-coupling and similarity-rs to run the same fast checks.
Limitations: The project is still under active development, and all operations should be carefully reviewed in production environments. State validation does not check all property values or output values. Live progress and restart recovery are not provided. Plan IDs are only valid within the current server process.
