Your First Terry-Form Project

Build a Docker image, configure your AI assistant, and run your first Terraform validation

beginner 15 minutes

Prerequisites

  • Docker installed and running
  • An MCP-compatible AI assistant (Claude Desktop, VS Code with Continue, etc.)
  • Basic familiarity with the command line

Your First Terry-Form Project

This tutorial walks you through building Terry-Form MCP, connecting it to your AI assistant, and running your first Terraform init-validate-plan cycle.

What You’ll Learn

  • How to build the Terry-Form MCP Docker image
  • How to configure your AI assistant’s MCP client
  • How to create a basic Terraform configuration
  • How to use the terry tool for init, validate, and plan

Step 1: Build the Docker Image

Clone the repository and build the image:

git clone https://github.com/aj-geddes/terry-form-mcp.git
cd terry-form-mcp
docker build -t terry-form-mcp .

Verify the build succeeded:

docker images | grep terry-form-mcp

You should see an image around 150MB based on Alpine Linux.

Step 2: Verify the Installation

Run the verification script to confirm everything is working:

scripts/verify.sh

This runs 8 checks: Docker availability, image size, Terraform version (1.12), terraform-ls version (0.38.5), Python version (3.10+), required files, tool registration, and server startup.

Step 3: Configure Your AI Assistant

Add Terry-Form MCP to your AI assistant’s MCP configuration.

Claude Desktop

Edit your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

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

Replace /path/to/your/workspace with the actual path where you’ll store Terraform files.

Important
Always use the -i flag (interactive). Terry-Form MCP uses stdio for communication — it will exit immediately without -i. Do NOT use -d (detached mode).

Restart Your Assistant

After saving the configuration, restart your AI assistant. It should now have access to 25 Terry-Form tools.

Step 4: Create a Terraform Configuration

Create a project directory in your workspace:

workspace/
└── hello-terraform/
    ├── main.tf
    └── variables.tf

main.tf:

terraform {
  required_version = ">= 1.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      Project   = "hello-terraform"
      ManagedBy = "Terraform"
    }
  }
}

resource "aws_s3_bucket" "example" {
  bucket_prefix = "terry-form-tutorial-"

  tags = {
    Name = "terry-form-tutorial"
  }
}

variables.tf:

variable "aws_region" {
  description = "AWS region for resources"
  type        = string
  default     = "us-east-1"
}

Step 5: Initialize and Validate

Ask your AI assistant:

“Initialize and validate my Terraform configuration in hello-terraform”

Behind the scenes, the assistant calls the terry tool:

{
  "tool": "terry",
  "arguments": {
    "path": "hello-terraform",
    "actions": ["init", "validate"]
  }
}

Expected response:

{
  "terry-results": [
    {
      "action": "init",
      "success": true,
      "stdout": "Terraform has been successfully initialized!"
    },
    {
      "action": "validate",
      "success": true,
      "stdout": "Success! The configuration is valid."
    }
  ]
}

Step 6: Generate a Plan

Now ask your assistant:

“Generate a Terraform plan for hello-terraform”

The assistant calls:

{
  "tool": "terry",
  "arguments": {
    "path": "hello-terraform",
    "actions": ["plan"]
  }
}

The plan output shows what Terraform would create — in this case, one S3 bucket. No resources are actually created; Terry-Form MCP blocks apply and destroy operations for safety.

Step 7: Check Your Work

Use the analysis tools to verify your configuration follows best practices:

“Analyze my hello-terraform configuration”

The assistant uses terry_analyze to check for:

  • Variables without descriptions
  • Hardcoded values (AMI IDs, VPC IDs, etc.)
  • Resources missing tags
  • Other best practice violations

What Just Happened?

You completed the standard Terry-Form workflow:

  1. init — Downloaded the AWS provider plugin
  2. validate — Verified the HCL syntax is correct
  3. plan — Previewed what would be created
  4. analyze — Checked for best practice violations

This init-validate-plan-analyze cycle is the foundation of all Terry-Form MCP workflows.

Understanding the Safety Model

Terry-Form MCP is intentionally read-only:

Allowed Blocked
init apply
validate destroy
fmt import
plan taint
show untaint

To actually create infrastructure, run terraform apply through your standard deployment process or CI/CD pipeline.

Next Steps

← Back to Tutorials Next: AWS Infrastructure →