Terraform MCP Server Explained: Setup and Use Cases

The popularity of agentic development extends to infrastructure as code. However, the lack of relevant context and up-to-date documentation and examples is problematic when using agents to author IaC with Terraform.

The model-context protocol (MCP) can help with elements of these issues. It does this by exposing capabilities to your agents in the form of tools that it can call to perform read or write operations in external systems, as well as resources and prompts.

In this blog post, we will explore the Terraform MCP server: what it is, how to configure and run it locally, examples of how it is used, and best practices.

What we’ll cover:

1. What is an MCP server?
2. What is the Terraform MCP server?
3. How to use the Terraform MCP server
4. Terraform MCP server use cases
5. Best practices for using the Terraform MCP server

TL;DR

The Terraform MCP server gives your AI agent live access to the public Terraform registry, so it writes Terraform with accurate, version-specific docs for providers, modules, and policies instead of outdated guesses.

• It runs locally, usually as a Docker container, so the token you give it never travels over the network.
• It ships with 44 tools. Most of them target HCP Terraform and Terraform Enterprise.
• Read-tools like search_providers are safe to run automatically. Action-tools like create_run can change or destroy infrastructure, so gate them behind a confirmation prompt.
• Destructive operations are off by default. ENABLE_TF_OPERATIONS is false until you set it to true.
• Scope the token to least privilege, and never hand the server credentials it doesn’t need.

What is an MCP server?

AI agents are based on large language models (LLMs). These models are trained on a huge amount of training data. This data represents a snapshot in time and does not include any new information that becomes available later.

To combat this, we extend our AI agents with knowledge in a few different formats:

• Retrieval-Augmented Generation (RAG) extends an agent with factual knowledge from some type of knowledge bank (e.g., an API, a database, a wiki, etc) at runtime.
• Fine-tuning is the process of training a base model on additional data within a specific domain.
• Agent skills allow you to extend an agent with procedural knowledge.
• The Model-Context Protocol (MCP) provides agents with knowledge in the form of tool access. This could be read-tools for reading up-to-date information or action-tools for performing operations on a remote system.

MCP is made available to your agents using a traditional client-server architecture. The agent is the client that calls the tools and resources exposed by the MCP server.

What is the Terraform MCP server?

The Terraform MCP server gives your AI agent tools to access up-to-date documentation on providers, modules, and policies from the public Terraform registry. This ensures your agent can provide accurate suggestions when assisting you with Terraform configurations.

The Terraform MCP server also provides your AI agent with tools to interact with your HCP Terraform organization to fetch information from your private registry and manage projects, workspaces, and runs.

A huge advantage of using the Terraform MCP server over giving your agent access to generic web-search tools is that you can pinpoint specific provider versions and resources to reduce the risk of model hallucinations or version mismatches in the generated code.

How to use the Terraform MCP server

In this section, we will follow the required steps to get the Terraform MCP server running locally.

How to install the Terraform MCP server locally

Generate a token to authenticate the Terraform MCP server

To interact with your HCP Terraform or Terraform Enterprise organization, you will need to provide the Terraform MCP server with a token. Sign in to your HCP Terraform or Terraform Enterprise organization, go to your user profile, and create a new user token.

Configure and run the Terraform MCP server locally

In this section, we will use the recommended option and host the Terraform MCP server locally using Docker.

Create a new directory named .vscode and create a file named mcp.json within this directory.

Add the following JSON configuration to mcp.json:

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_TOKEN=${input:tfe_token}",
        "-e", "TFE_ADDRESS=${input:tfe_address}",
        "-e", "ENABLE_TF_OPERATIONS=true",
        "hashicorp/terraform-mcp-server"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}

Use case 1: Interacting with the public Terraform registry

When you use a foundation LLM model with no additional source of knowledge to generate a Terraform configuration, you commonly end up with older Terraform provider versions that do not have the latest features, resources, and behaviors. The Terraform MCP server can rectify this through tools that interact with the public Terraform registry.

Use case 2: Interacting with HCP Terraform or Terraform Enterprise

The Terraform MCP server can help during operations of Terraform configurations in your HCP Terraform or Terraform Enterprise environments. You can perform tasks like listing projects and workspaces, managing variables, or triggering terraform plan and apply operations via your agent.

Use cases for the Terraform MCP server

• Access Terraform registry documentation for providers, modules, and Sentinel policies.
• Interact with your Terraform Enterprise (TFE) or HCP Terraform environment:
  • List your organizations, projects and workspaces.
  • Manage workspaces (create, update, delete).
  • List, create, update and delete variables and variable sets.
  • Create and manage runs and monitor run status.
• Produce higher-quality Terraform configurations by giving your agent access to the Terraform style-guide and the module development guide.

Best practices for using the Terraform MCP server

• Host your Terraform MCP server locally: Do not expose the server over a network unless you have specific requirements.
• Restrict token permissions (least privilege): Scope the token to the actions it must be able to perform. Use team tokens instead of user tokens if possible.
• Handle action-tools carefully: Do not allow the use of action-tools in production without confirmation. Keep ENABLE_TF_OPERATIONS as false unless needed.
• Do not expose sensitive data: Use OIDC workload identity federation for cloud authentication instead of passing static credentials to the MCP server.
• Monitor and logging: Use variables like LOG_LEVEL to track usage, especially for action-tools.

Frequently asked questions

• Is there an MCP for Terraform? Yes, HashiCorp maintains the official Terraform MCP server.
• How does the Terraform MCP server work? It runs as a local or remote server that exposes Terraform Registry APIs and HCP Terraform operations through JSON-RPC 2.0.
• What are the benefits of using Terraform MCP? It provides real-time access to current provider schemas and manages HCP Terraform/Enterprise operations directly.
• Is the Terraform MCP server open source? Yes, under the Mozilla Public License 2.0.