Terry-Form MCP

AI-powered Terraform execution through the Model Context Protocol.

Terry-Form MCP is a containerized Model Context Protocol server that gives AI assistants like Claude safe, structured access to Terraform. It exposes 25 MCP tools spanning Terraform execution, LSP intelligence, GitHub integration, and Terraform Cloud connectivity — all running inside Docker with destructive operations blocked by design.

Documentation Site

Dashboard

The built-in web dashboard provides real-time server health monitoring, tool category overview, and integration status at a glance. Live status auto-refreshes every 5 seconds.

Configuration UI

A tabbed configuration interface lets you manage server settings, integrations, cloud provider credentials, and rate limits — all without touching config files. Built with the HAT stack (HTMX + Alpine.js + Tailwind CSS).

GitHub Integration	Cloud Providers	Rate Limits

Tool Catalog

The interactive tool catalog at /tools lists all 25 MCP tools with search, category filtering, and expandable parameter details. Also available as a raw JSON endpoint at /api/tools and as a static tools.json file.

Quick Start

Prerequisites

• Docker installed and running
• Python >= 3.10 (for local development)

1. Build

scripts/build.sh      # Linux/macOS
scripts\build.bat     # Windows
# or directly:
docker build -t terry-form-mcp .

2. Run as MCP Server

docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

3. Verify the Image

scripts/verify.sh   # Runs 8 checks: Docker, image size, Terraform, terraform-ls, Python, files, tools, startup

Environment Variables

All configuration is through environment variables. No config file is required for basic use.

Server Configuration

Terraform

LSP

GitHub Integration

Terraform Cloud

Rate Limits

Cloud Provider Passthrough

These variables are forwarded directly to the Terraform subprocess. Set them to authenticate with your cloud provider.

AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_REGION, AWS_PROFILE

GCP: GOOGLE_CREDENTIALS, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_PROJECT, GOOGLE_REGION, GOOGLE_ZONE

Azure: ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID, ARM_TENANT_ID

MCP Client Configuration

Add Terry-Form to any MCP-compatible client:

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/workspace:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YourUsername\\terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YourUsername/terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcp.servers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Tools (25)

Core Terraform

# Initialize and validate a project
terry(path="infrastructure/aws", actions=["init", "validate"])

# Plan with variables
terry(path="environments/prod", actions=["plan"], vars={"instance_count": "3", "region": "us-east-1"})

Only init, validate, fmt, and plan are permitted. apply and destroy are blocked.

LSP Intelligence

# Code completions
terraform_complete(file_path="main.tf", line=10, character=0)

# Hover documentation
terraform_hover(file_path="main.tf", line=15, character=12)

# Detailed validation with error locations
terraform_validate_lsp(file_path="main.tf")

# Format a file
terraform_format_lsp(file_path="main.tf")

Powered by terraform-ls v0.38.5 — provides context-aware completions, inline documentation, and diagnostics with precise source locations.

GitHub Integration

# Clone a repo and prepare it for Terraform operations
github_clone_repo(owner="myorg", repo="infrastructure")
github_prepare_workspace(owner="myorg", repo="infrastructure", config_path="environments/prod")

Security Scanning

# Scan for hardcoded credentials, missing encryption, overly permissive policies
terry_security_scan(path="my-project")

# Get actionable improvement recommendations
terry_recommendations(path="my-project")

Architecture

┌─────────────┐     MCP Protocol     ┌──────────────────────────────────────┐
│ AI Assistant │ ◄──────────────────► │  Terry-Form MCP Server               │
│ (Claude)     │                      │                                      │
└─────────────┘                      │  ┌─────────────┐  ┌──────────────┐  │
                                     │  │ Terraform    │  │ terraform-ls │  │
                                     │  │ CLI 1.12     │  │ LSP 0.38.5   │  │
                                     │  └──────┬───────┘  └──────┬───────┘  │
                                     │         │                 │          │
                                     │         ▼                 ▼          │
                                     │  ┌──────────────────────────────┐   │
                                     │  │   /mnt/workspace (isolated)   │   │
                                     │  └──────────────────────────────┘   │
                                     └──────────────────────────────────────┘
                                              Docker Container

Key Components

Frontend Stack

The built-in web UI uses the HAT stack:

• HTMX 2.0 — partial page updates without full reloads
• Alpine.js 3.14 — lightweight client-side reactivity for tabs and toasts
• Tailwind CSS — dark-mode-first utility styling

Accessible at the server root when running with streamable-http or sse transport.

Security Model

Terry-Form implements defense-in-depth with four layers:

Forced environment variables: TF_IN_AUTOMATION=true, TF_INPUT=false, CHECKPOINT_DISABLE=true.

Running with the Web UI

To use the dashboard and configuration UI, run with HTTP transport:

# Local
MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 python3 src/server_enhanced_with_lsp.py

# Docker
docker run -it --rm \
  -p 8000:8000 \
  -v "$(pwd)":/mnt/workspace \
  -e MCP_TRANSPORT=streamable-http \
  terry-form-mcp

Then open http://localhost:8000 in your browser.

Configuration Tabs

Container Details

Built on hashicorp/terraform:1.12 (Alpine-based, ~150MB). Includes:

• Terraform CLI 1.12
• terraform-ls v0.38.5 for LSP support
• Python 3.12 with FastMCP 3.0+
• Runs as non-root user terraform (UID 1001)

Development

# Install dependencies
pip install -r requirements.txt

# Run locally
python3 src/server_enhanced_with_lsp.py

# Code quality
black .       # Format (88-char line limit)
flake8 .      # Lint
mypy src/*.py # Type check

Limitations

• No state modification — apply and destroy are intentionally blocked
• String variables only — complex variable types not supported via CLI passthrough
• LSP cold start — first LSP operation takes 1-2 seconds for initialization
• Local execution — designed for development workflows, not production CI/CD

License

MIT