nwiizo/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.2 is the current release:

cargo install tfmcp --version 0.2.2

What's new in v0.2.2

• RMCP 3.0.1 and MCP 2026-07-28 discovery support

• Structured JSON tool results with backward-compatible text content

• Five-minute public cache hints for tool and resource discovery

• Sessionless Streamable HTTP behavior for MCP 2026-07-28 clients

• Capability metadata aligned with the methods tfmcp implements

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, MCP 2026-07-28 discovery, structured tool results, cache hints, 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:

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 82 MCP tools for AI assistants:

Core Terraform Operations

Workspace & State (v0.1.9)

Code & Output (v0.1.9)

Analysis & Security

Registry

HCP Terraform / Terraform Enterprise (Read-only)

HCP Terraform / Terraform Enterprise (Gated Operations)

MCP Resources

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: tfmcp advertises and implements tools/list, resources/list, resources/templates/list, and resources/read

• 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). Applies only to clients negotiating a protocol version before 2026-07-28; that spec removed sessions, so those requests are always served statelessly.

• 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). Clients negotiating 2026-07-28 send no session header, so only MCP_RATE_LIMIT_GLOBAL bounds them.

• 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. Enable the repository-managed fast pre-commit checks once per clone:

git config core.hooksPath .githooks

cargo fmt --all -- --check
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test --locked --all-targets --all-features

The pre-commit hook always checks staged whitespace and conditionally runs
cargo fmt, actionlint, Registry metadata validation, module coupling, and
duplicate-code checks for affected files. The optional architecture tools are
still mandatory in Release.sh; install cargo-coupling and similarity-rs
to run the same fast feedback while developing.

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.2.
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.2 --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

• [x] MCP Server Implementation

• [x] Automatic Project Creation

• [x] Claude Desktop Integration

• [x] Core MCP Methods

• [x] Error Handling Improvements

• [x] Dynamic Project Directory Switching

• [x] Crates.io Publication

• [x] Docker Support

• [x] Security Enhancements

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

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

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

• [x] Comprehensive Testing Framework

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

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

In Progress

• [ ] Multi-Environment Support

Planned

• [ ] Expanded MCP Protocol Support

• [ ] Performance Optimization

• [ ] Cost Estimation

• [ ] Interactive TUI

• [ ] Integration with Other AI Platforms

• [ ] Plugin System

License

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