tfmcp

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

🎉 Current Release

tfmcp v0.2.1 is the current release:

cargo install tfmcp --version 0.2.1

What's new in v0.2.1

• HCP/TFE read coverage and explicitly gated write operations
• Streamable HTTP with loopback-safe Host and Origin validation
• Project inspection, plan review, lockfile checks, and state-safety workflows
• Terraform 1.15.8 CI and container baseline
• Rust module-boundary and duplicate-code release gates

Features

| Area | Capabilities | | --- | --- | | Local Terraform | Validate, format, plan/apply workflows, import guidance, outputs, providers, dependency graphs, refresh-only flows, and guarded state operations | | Repository intelligence | Entrypoint/project detection, configuration analysis, quality checks, security checks, module health, plan review, and drift/state-safety inspection | | Registry | Public/private provider, module, and policy lookup with HashiCorp-compatible aliases | | HCP Terraform / TFE | Organizations, projects, workspaces, runs, plans, applies, variables, policy sets, variable sets, tags, stacks, and gated operations | | MCP deployment | stdio and Streamable HTTP, toolsets, resources, health/metrics, sessions, Host/Origin validation, rate limits, TLS wiring, and audit logging | | Packaging | Cargo, Docker/OCI metadata, MCP Registry metadata, Rust Edition 2024 |

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
• 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: ``bash docker build -t tfmcp . ``

1. Find the path to your installed tfmcp executable:

   which tfmcp

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

1. Restart Claude Desktop and enable the tfmcp tool.

1. 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 82 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 | | review_terraform_plan | Review plan risk, blockers, destructive changes, and recommendations | | summarize_plan_for_pr | Generate markdown plan summary for PR comments | | run_terraform_quality_checks | Run CI-friendly validation, module health, guideline, and lockfile checks | | inspect_state_safety | Inspect state readability, drift risk, lockfile status, and blockers | | detect_drift_candidates | Detect drift candidates from readable state without modifying infrastructure | | prepare_terraform_change | Generate blockers, warnings, and a recommended change sequence | | 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 | | check_provider_lockfile | Check .terraform.lock.hcl for reproducible provider selections |

Analysis & Security

| Tool | Description | |------|-------------| | analyze_terraform | Analyze configuration | | inspect_terraform_project | Inspect local Terraform directories, modules, and likely entrypoints | | detect_terraform_entrypoints | Detect likely root module entrypoints | | 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_providers | Search providers (HashiCorp-compatible alias) | | search_terraform_providers | Search providers | | get_provider_details | Provider details (HashiCorp-compatible alias) | | get_provider_info | Provider details | | get_provider_docs | Provider documentation | | get_provider_capabilities | Provider resources, data sources, functions, and guides | | search_modules | Search modules (HashiCorp-compatible alias) | | search_terraform_modules | Search modules | | get_module_details | Module details | | get_latest_module_version | Latest module version | | get_latest_provider_version | Latest provider version | | search_policies | Search Sentinel/OPA policy libraries | | get_policy_details | Policy library details |

HCP Terraform / Terraform Enterprise (Read-only)

| Tool | Description | |------|-------------| | get_token_permissions | Inspect configured token account details without exposing the token | | list_terraform_orgs | List visible organizations | | list_terraform_projects | List projects in an organization | | list_workspaces | List workspaces in an organization | | get_workspace_details | Get workspace details by ID or organization/name | | list_runs | List workspace runs | | get_run_details | Get run details | | get_plan_details | Get plan details | | get_plan_logs | Get plan logs | | get_plan_json_output | Get Terraform JSON plan output | | get_apply_details | Get apply details | | get_apply_logs | Get apply logs | | get_workspace_policy_sets | Get policy sets attached to a workspace | | list_workspace_variables | List workspace variables | | list_variable_sets | List organization variable sets | | read_workspace_tags | Read workspace tags | | list_stacks | List Terraform stacks | | get_stack_details | Get Terraform stack details | | search_private_modules | Search private registry modules | | get_private_module_details | Get private registry module details | | search_private_providers | Search private registry providers | | get_private_provider_details | Get private registry provider details |

HCP Terraform / Terraform Enterprise (Gated Operations)

| Tool | Description | |------|-------------| | create_workspace | Create a workspace when ENABLE_TF_OPERATIONS=true | | update_workspace | Update workspace settings when ENABLE_TF_OPERATIONS=true | | delete_workspace_safely | Use the safe-delete workspace action when ENABLE_TF_OPERATIONS=true | | create_run | Queue a run when ENABLE_TF_OPERATIONS=true | | action_run | Apply, discard, cancel, force-cancel, or force-execute a run when ENABLE_TF_OPERATIONS=true | | create_workspace_variable | Create a workspace variable when ENABLE_TF_OPERATIONS=true | | update_workspace_variable | Update a workspace variable when ENABLE_TF_OPERATIONS=true | | attach_policy_set_to_workspace | Attach a policy set to a workspace when ENABLE_TF_OPERATIONS=true | | create_variable_set | Create a variable set when ENABLE_TF_OPERATIONS=true | | create_variable_in_variable_set | Create a variable in a variable set when ENABLE_TF_OPERATIONS=true | | delete_variable_in_variable_set | Delete a variable from a variable set when ENABLE_TF_OPERATIONS=true | | attach_variable_set_to_workspaces | Attach a variable set to workspaces when ENABLE_TF_OPERATIONS=true | | detach_variable_set_from_workspaces | Detach a variable set from workspaces when ENABLE_TF_OPERATIONS=true | | create_workspace_tags | Create or attach workspace tags when ENABLE_TF_OPERATIONS=true |

MCP Resources

| URI | Description | |-----|-------------| | terraform://style-guide / /terraform/style-guide | Terraform style guide | | terraform://module-development / /terraform/module-development | Terraform module development guide | | terraform://best-practices | tfmcp security and operational best practices | | /terraform/providers/{namespace}/name/{name}/version/{version} | HashiCorp-compatible provider documentation template |

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

• ENABLE_TF_OPERATIONS: Set to true to enable gated HCP Terraform / Terraform Enterprise write tools (default: false)
• 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)

HCP Terraform / Terraform Enterprise

• TFE_ADDRESS: HCP Terraform or Terraform Enterprise base URL (default: https://app.terraform.io)
• TFE_TOKEN: API token for HCP Terraform / Terraform Enterprise tools
• TFE_SKIP_TLS_VERIFY: Set to true only for trusted private TFE installations with custom TLS
• TFE_MAX_RESPONSE_BYTES: Maximum HCP/TFE response bytes returned to MCP clients before truncation (default: 65536)

HCP/TFE write tools are disabled by default and fail closed unless ENABLE_TF_OPERATIONS=true is set. The default toolset keeps write tools hidden; use --toolsets operations or --toolsets all to expose them.

MCP Transport

• TRANSPORT_MODE: MCP transport mode. Use stdio (default) for local desktop clients or streamable-http for remote/CI clients.
• TRANSPORT_HOST: HTTP bind host for streamable HTTP mode (default: 127.0.0.1).
• TRANSPORT_PORT: HTTP bind port for streamable HTTP mode (default: 8080).
• MCP_ENDPOINT: Streamable HTTP MCP endpoint path (default: /mcp).
• MCP_HEALTH_ENDPOINT: Health endpoint path (default: /health).
• MCP_METRICS_ENDPOINT: OTel-compatible JSON metrics snapshot endpoint path (default: /metrics).
• MCP_SESSION_MODE: stateful for normal MCP clients or stateless for CI-style JSON responses (default: stateful).
• MCP_HEARTBEAT_INTERVAL: Streamable HTTP SSE keep-alive interval in seconds. Set to 0 to disable (default: 15).
• MCP_CORS_MODE: Response CORS policy: strict, development, or disabled (default: strict). MCP request Origin validation remains enabled in all modes.
• MCP_ALLOWED_ORIGINS: Comma-separated allowed browser origins. Loopback origins are used by default.
• MCP_ALLOWED_HOSTS: Comma-separated HTTP Host / authority values accepted by Streamable HTTP. When unset, rmcp's loopback-only defaults apply.
• MCP_ORGANIZATION_ALLOWLIST: Comma-separated HCP/TFE organization names that remote requests may access.
• MCP_RATE_LIMIT_GLOBAL: Maximum HTTP requests per minute across the server (0 or unset disables).
• MCP_RATE_LIMIT_SESSION: Maximum HTTP requests per minute per Mcp-Session-Id (0 or unset disables).
• MCP_TLS_CERT_FILE: PEM certificate file for HTTPS Streamable HTTP.
• MCP_TLS_KEY_FILE: PEM private key file for HTTPS Streamable HTTP.

HCP/TFE credentials and addresses are server configuration. tfmcp intentionally does not accept request-scoped TFE_TOKEN, Authorization, or TFE_ADDRESS overrides for downstream passthrough. When an organization allowlist is active, account-wide and ID-only HCP/TFE requests fail closed because their owning organization cannot be verified locally.

Example streamable HTTP launch:

TRANSPORT_MODE=streamable-http \
TRANSPORT_HOST=127.0.0.1 \
TRANSPORT_PORT=8080 \
tfmcp mcp --toolsets default

The MCP endpoint is http://127.0.0.1:8080/mcp, the health endpoint is http://127.0.0.1:8080/health, and the metrics endpoint is http://127.0.0.1:8080/metrics.

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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run quality checks before committing:

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

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

Release Process

Releases are done manually after the local release gate passes:

1. Confirm Cargo.toml, Cargo.lock, server.json, Dockerfile, README, and CHANGELOG.md use the target version.
2. Run the local release gate: ./Release.sh v0.2.1.
3. Review CHANGELOG.md and the generated package.
4. Commit and push main, then confirm CI passed for that exact commit.
5. From the clean commit, publish with ./Release.sh v0.2.1 --publish.

Roadmap

Here are some planned improvements and future features for tfmcp:

For the consolidated v0.2.1 scope and future work, see docs/releases/v0.2-roadmap.md. Release changes are recorded in CHANGELOG.md.

Completed

• [x] Basic Terraform Integration

Core integration with Terraform CLI for analyzing and executing operations.

• [x] MCP Server Implementation

Initial implementation of the Model Context Protocol server for AI assistants.

• [x] Automatic Project Creation

Added functionality to automatically create sample Terraform projects when needed.

• [x] Claude Desktop Integration

Support for seamless integration with Claude Desktop.

• [x] Core MCP Methods

Implementation of essential MCP methods including resources/list and prompts/list.

• [x] Error Handling Improvements

Better error handling and recovery mechanisms for robust operation.

• [x] Dynamic Project Directory Switching

Added ability to change the active Terraform project directory without restarting the service.

• [x] Crates.io Publication

Published the package to Crates.io for easy installation via Cargo.

• [x] Docker Support

Added containerization support for easier deployment and cross-platform compatibility.

• [x] Security Enhancements

Comprehensive security system with configurable policies, audit logging, access controls, and production-ready safety features.

• [x] Module Health Analysis (v0.1.6)

Whitebox approach to IaC with cohesion/coupling metrics, health scoring, and refactoring suggestions.

• [x] Resource Dependency Graph (v0.1.6)

Visualization of resource relationships including explicit and implicit dependencies.

• [x] Module Registry Integration (v0.1.6)

Search and explore Terraform modules from the registry.

• [x] Comprehensive Testing Framework

85+ tests including integration tests with real Terraform configurations.

• [x] RMCP SDK Migration (v0.1.8)

Migrated to official RMCP SDK with proper tool annotations for better MCP compliance.

• [x] Future Architect Guidelines (v0.1.8)

Terraform coding standards compliance checks with secret detection and variable quality validation.

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.

License

This project is licensed under the MIT License - see the LICENSE file for details.