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

🎉 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

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

4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. 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

• Basic Terraform Integration Core integration with Terraform CLI for analyzing and executing operations.

• MCP Server Implementation Initial implementation of the Model Context Protocol server for AI assistants.

• Automatic Project Creation Added functionality to automatically create sample Terraform projects when needed.

• Claude Desktop Integration Support for seamless integration with Claude Desktop.

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

• Error Handling Improvements Better error handling and recovery mechanisms for robust operation.

• Dynamic Project Directory Switching Added ability to change the active Terraform project directory without restarting the service.

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

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

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

• Module Health Analysis (v0.1.6) Whitebox approach to IaC with cohesion/coupling metrics, health scoring, and refactoring suggestions.

• Resource Dependency Graph (v0.1.6) Visualization of resource relationships including explicit and implicit dependencies.

• Module Registry Integration (v0.1.6) Search and explore Terraform modules from the registry.

• Comprehensive Testing Framework 85+ tests including integration tests with real Terraform configurations.

• RMCP SDK Migration (v0.1.8) Migrated to official RMCP SDK with proper tool annotations for better MCP compliance.

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