Terry-Form MCP Server

How to use

You use Terry-Form MCP by running its container and then sending Terraform-related requests from your MCP client. The server restricts operations to safe actions and provides LSP-powered development features that help you write, validate, and plan Terraform configurations without modifying state.

Typical patterns you’ll follow include initializing workspaces, validating and formatting Terraform code, and generating plans. You can also leverage LSP capabilities for real-time hover explanations, completions, and diagnostics as you edit your Terraform files. All actions occur inside the container, using a mounted workspace in /mnt/workspace.

How to install

Prerequisites you need before starting: Docker installed and running, Python 3.8 or newer for development/testing, and access to your Terraform configurations in your workspace.

Step 1: Build the Docker image. You have two primary options. Use the provided script for a streamlined build, or build directly with Docker.

# Build using the provided script (Linux/macOS)
./build.sh

# Or for Windows users
build.bat

# Alternatively, build directly with Docker
docker build -t terry-form-mcp .

Step 2: Run Terry-Form MCP as a server in a container and mount your workspace. The following command starts the server and shares your current directory as /mnt/workspace inside the container.

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

Additional configuration and usage notes

You can perform a broad set of Terraform actions in read-only mode inside isolated containers. The architecture ensures workspace isolation by mounting your local workspace at /mnt/workspace and restricting access to those files. You can query environment readiness and LSP status to verify that the system is prepared for development.

Common workflow includes: initializing a workspace, running a plan, and using LSP features for code completion and diagnostics. The system supports batch operations and returns JSON-structured results for easy consumption by AI tools.

If you want to check readiness before development, you can run an environment check to confirm Terraform and the LSP integration are available.

Configuration

MCP server configuration in IDEs typically involves pointing the MCP client to the terry-form-mcp container and mounting your workspace. The example below demonstrates a generic configuration shape that works across environments.

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "$(pwd):/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Security and safe operations

Security is built into the execution model. All Terraform commands run in ephemeral Docker containers, with read-only mounts for your workspace and no access to external networks. Only safe operations are allowed, such as init, validate, fmt, and plan. Destructive actions like apply or destroy are blocked to prevent unintended changes.

Key safety features include path validation, input sanitization, and structured output that makes it easier to reason about results from AI assistants.

Troubleshooting

LSP not initializing or features not working? Check the LSP status and environment readiness, then initialize the LSP client for your workspace if needed.

If Docker mount issues occur, verify the host paths and file permissions for the workspace you mounted into /mnt/workspace.

For Terraform execution errors, ensure you have initialized the workspace and validated syntax with LSP-based diagnostics.

Development and testing tips

Use verbose debugging to troubleshoot locally. You can enable detailed Python logs and run the container in interactive mode to observe behavior.

If you want to customize the image, you can modify the Dockerfile and rebuild the image with Docker.

Usage examples overview

Basic Terraform execution example: initialize and validate a project with Terry-Form MCP, then proceed to plan as needed.

LSP-powered development example: initialize the LSP client for a workspace, request hover information and completions, format files via LSP, and validate with diagnostics.

terry

Executes Terraform commands in a containerized environment and returns structured results.

terraform_validate_lsp

Validates Terraform files using LSP for detailed diagnostics.

terraform_hover

Provides documentation for Terraform elements at a given cursor position.

terraform_complete

Offers intelligent code completion suggestions for Terraform files.

terraform_format_lsp

Formats Terraform files using LSP-powered formatting.

terraform_lsp_status

Checks the status of the terraform-ls Language Server.

terry_environment_check

Checks the environment for Terraform and LSP readiness.

terry_lsp_debug

Gives detailed debugging information for the LSP integration.

terry_workspace_info

Analyzes Terraform workspace structure and readiness.

terry_lsp_init

Manually initializes the LSP client for a workspace.

terry_file_check

Checks a Terraform file for syntax and structure issues.

terry_workspace_setup

Creates a properly structured Terraform workspace.

terry_version

Gets Terraform and server version information.

terry_workspace_list

Lists all Terraform workspaces in the mounted directory.

terry_analyze

Analyzes Terraform configuration for best practices.

terry_recommendations

Provides improvement recommendations for Terraform code.

terry_security_scan

Scans Terraform configuration for security issues.

github_clone_repo

Clones or updates a GitHub repository.

github_list_terraform_files

Lists Terraform files in a repository.

github_get_terraform_config

Gets information about Terraform configuration in a repository.

github_prepare_workspace

Prepares a Terraform workspace from a GitHub repository.

tf_cloud_list_workspaces

Lists Terraform Cloud workspaces in an organization.

tf_cloud_get_workspace

Gets detailed workspace information in TF Cloud.

tf_cloud_list_runs

Lists recent runs for a workspace in TF Cloud.

tf_cloud_get_state_outputs

Gets state outputs from a TF Cloud workspace.