Getting Started with Terry-Form MCP

Welcome to Terry-Form MCP! This guide will help you get up and running quickly.

Prerequisites

Before you begin, ensure you have:

Docker (recommended) or Python 3.10+
An AI assistant that supports MCP (Claude Desktop, etc.)
A workspace directory for your Terraform configurations

Installation

Option 1: Docker (Recommended)

Docker provides the easiest and most secure way to run Terry-Form MCP.

# Clone the repository
git clone https://github.com/aj-geddes/terry-form-mcp.git
cd terry-form-mcp

# Build the image
scripts/build.sh

# Verify the build (8 checks)
scripts/verify.sh

Option 2: Local Development

For development or testing:

# Clone the repository
git clone https://github.com/aj-geddes/terry-form-mcp.git
cd terry-form-mcp

# Install dependencies (requires Python 3.10+)
pip install -r requirements.txt

# Run the server directly
python3 src/server_enhanced_with_lsp.py

Configuration

MCP Client Configuration

Configure your AI assistant to use Terry-Form MCP. For Claude Desktop, edit your claude_desktop_config.json:

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

Note
Terry-Form MCP uses stdio transport for the MCP protocol. The Docker container runs interactively (-i) and is invoked by your MCP client — it is not a daemon or HTTP server.

Environment Variables

Optional environment variables for extended features:

Variable	Description	Required
`GITHUB_APP_ID`	GitHub App ID for repo integration	No
`GITHUB_APP_INSTALLATION_ID`	GitHub App installation ID	No
`GITHUB_APP_PRIVATE_KEY`	GitHub App private key (PEM)	No
`TF_CLOUD_TOKEN`	Terraform Cloud API token	No
`LOG_LEVEL`	Logging level (INFO, DEBUG)	No

Forced Environment Variables

These are always set inside the container and cannot be overridden:

Variable	Value	Purpose
`TF_IN_AUTOMATION`	`true`	Suppresses interactive prompts
`TF_INPUT`	`false`	Prevents input requests
`CHECKPOINT_DISABLE`	`true`	Disables Terraform update checks

Security Configuration

Terry-Form MCP includes several security features by default:

Allowed actions: init, validate, plan, fmt, show, graph, providers, version
Blocked actions: apply, destroy, import, taint, untaint
Path validation: All paths restricted to /mnt/workspace
Input sanitization: Dangerous characters blocked in variable values
Rate limiting: 20 req/min (Terraform), 30 req/min (GitHub)

Your First Terraform Operation

1. Create a Simple Configuration

Create a file workspace/main.tf:

terraform {
  required_version = ">= 1.0"
}

variable "project_name" {
  description = "Name of the project"
  type        = string
  default     = "my-first-project"
}

output "project_info" {
  value = "Project: ${var.project_name}"
}

2. Use Terry-Form with Your AI Assistant

Ask your AI assistant:

Can you help me validate and plan my Terraform configuration in the workspace directory?

The assistant will use Terry-Form MCP to:

Initialize the Terraform workspace (terry with actions: ["init"])
Validate the configuration (terry with actions: ["validate"])
Generate an execution plan (terry with actions: ["plan"])
Provide feedback and recommendations

3. Example Response

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

Common Use Cases

Managing Multiple Environments

Ask your AI assistant to plan different environments:

Plan my Terraform configuration at "environments/dev" with variable env="development"

Plan my Terraform configuration at "environments/prod" with variable env="production"

Working with Modules

# workspace/modules/vpc/main.tf
module "vpc" {
  source = "./modules/vpc"

  cidr_block  = var.vpc_cidr
  environment = var.environment
}

GitHub Integration

If you’ve configured GitHub App integration:

Clone the repository myorg/infrastructure from GitHub and list its Terraform files

The assistant will use github_clone_repo followed by github_list_terraform_files.

Troubleshooting

Common Issues

Permission Denied
Ensure the workspace directory has proper permissions. The container runs as UID 1001: chmod -R 755 /path/to/workspace

Terraform Not Found
If using Docker, Terraform 1.12 is included in the image. For local setup, install Terraform separately.

MCP Connection Failed
Ensure Docker is running and the image is built. Test with: docker run -i --rm terry-form-mcp:latest python3 -c "print('OK')"

Debug Mode

Enable debug logging:

docker run -i --rm \
  -e LOG_LEVEL=DEBUG \
  -v /path/to/workspace:/mnt/workspace \
  terry-form-mcp:latest

Best Practices

Use Version Control: Always version control your Terraform configurations
Plan Before Apply: Review plans carefully (apply is blocked by design)
Use Workspaces: Separate environments using directory structure
Secure Secrets: Pass cloud credentials via environment variables
Regular Updates: Keep the Docker image updated for security patches

Next Steps

Getting Help

Congratulations!
You've successfully set up Terry-Form MCP. Start exploring its features and automate your infrastructure with confidence!