Terraform MCP

The Terraform MCP server is HashiCorp's own bridge between an AI agent and the Terraform ecosystem. Without a token it answers questions from the public registry: provider docs, modules and Sentinel policies. With an HCP Terraform or Terraform Enterprise token it can also manage workspaces, projects, teams and runs. We checked it on 31 October 2026, and the latest release then was v1.4.1.

Quick facts

The repository describes the server as an integration for "advanced automation and interaction capabilities for Infrastructure as Code (IaC) development". In plain terms, there are two jobs. One is a documentation lookup so the agent stops guessing at resource arguments. The other is a control panel for the HCP Terraform API.

What it does

Language models are weak at Terraform for a boring reason. Providers ship new versions all the time, and an argument that existed last year may be gone. A model that writes aws_s3_bucket blocks from memory often mixes old and new syntax. The server fixes that by letting the agent ask the registry for the current docs of the exact provider version before it writes the code.

The second job is operational. If your team runs HCP Terraform, the agent can list organizations, find a workspace, read a run's plan, check variables and, if you allow it, start or approve a run. That is useful for questions like "why did the last run in prod-network fail?" and risky for questions like "clean up the old workspaces".

The README lists four main features: dual transport support, registry integration for providers, modules and policies, HCP Terraform and Terraform Enterprise support for workspace operations, and OpenTelemetry metrics for tool use in HTTP mode.

The tools

HashiCorp's reference page groups tools into three toolsets. The server registers the registry-private and terraform tools only when you give it a valid TFE_TOKEN. If you start it with no --toolsets flag, it enables all toolsets.

Public registry tools (registry)

Private registry tools (registry-private)

search_private_modules, get_private_module_details, search_private_providers and get_private_provider_details read the private registry of your HCP Terraform or Terraform Enterprise organization. They need a token.

HCP Terraform and Enterprise tools (terraform)

The reference page continues past runs with more tools for plans, applies, variables and similar items. [VERIFY: the full tool list past get_plan_details on the reference page, since we only confirmed the groups above]. We did not count tools, and the README says to check pkg/toolsets/mapping.go for exact names, so use that file if you need to allow-list individual tools.

Several of these are marked as destructive in the docs. create_workspace and update_workspace carry a warning that they change things. delete_project, delete_team, delete_workspace_safely, force_unlock_workspace and action_run (apply, discard or cancel) all need ENABLE_TF_OPERATIONS=true. create_no_code_workspace uses MCP elicitation, which means the agent must ask you for module variables mid-task. Your client has to support that. See MCP clients for how agents differ here.

Filtering tools

The --toolsets flag picks groups and the --tools flag picks individual tools. You cannot use both at once. Our suggestion is to start read-only:

terraform-mcp-server --toolsets=registry

What it costs

The server is free. The Terraform Registry is public. HCP Terraform has its own plans and the terraform toolset works only against an account you already have, so any bill is the one you already pay HashiCorp. We found nothing in the README that charges for MCP use. [VERIFY: whether the hosted mcp.terraform.io endpoint needs a particular HCP Terraform plan, on developer.hashicorp.com].

Install it

HashiCorp documents Docker as the main route, with a binary for people who build from source. You need Docker running, plus an MCP-capable agent.

Local, stdio, public registry only

docker run -i --rm hashicorp/terraform-mcp-server

Local, with HCP Terraform access

docker run -i --rm \
  -e TFE_TOKEN=$TFE_TOKEN \
  -e TFE_ADDRESS=https://app.terraform.io \
  hashicorp/terraform-mcp-server:1.4.1

Pin a version tag in anything you share with a team. The README's own OpenCode example pins 1.4.1.

Streamable HTTP

terraform-mcp-server streamable-http --transport-port 8080

The endpoint is then http://127.0.0.1:8080/mcp, with a health check at /health. Rate limits default to 10 requests a second globally and 5 per session, with bursts of 20 and 10.

Install it in each agent

The README has sections for Claude Code, Codex, OpenCode, Cursor, VS Code, Claude Desktop, Gemini extensions and others. Antigravity is not in it, so that line is our adaptation. For field names across agents, see MCP clients.

Claude Code

From the README:

claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

Remote, with a token:

claude mcp add terraform -s user -t http \
  --header "Authorization: Bearer <<TFE_TOKEN>>" \
  https://mcp.terraform.io/mcp

Codex

From the README:

codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

The README says codex mcp add has no flag for custom headers, so for the remote endpoint edit ~/.codex/config.toml:

[mcp_servers.terraform]
url = "https://mcp.terraform.io/mcp"
http_headers = { "Authorization" = "Bearer <<TFE_TOKEN>>" }

To pass credentials to the local container, add TFE_ADDRESS and TFE_TOKEN to the Docker command, as the README notes.

Cursor

The README's entry goes in ~/.cursor/mcp.json or the MCP settings page:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "hashicorp/terraform-mcp-server"]
    }
  }
}

[VERIFY: the exact env entries the README shows for Cursor, since we kept the minimal form].

Antigravity

Our adaptation. Put the same stdio entry in ~/.gemini/config/mcp_config.json under mcpServers. For the hosted endpoint, Antigravity takes the URL in serverUrl. [VERIFY: whether Antigravity can send an Authorization header to mcp.terraform.io, on antigravity.google/docs/mcp]. Gemini CLI is now for Code Assist enterprise customers only, so we do not give a line for it, although the README documents a Gemini extension route.

OpenCode

The README documents OpenCode. Its snippet nests servers under mcp.servers, which is different from the flat mcp map described in OpenCode's own docs. Our adaptation follows OpenCode's docs, in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "terraform": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm",
                  "-e", "TFE_ADDRESS", "-e", "TFE_TOKEN",
                  "hashicorp/terraform-mcp-server:1.4.1"],
      "environment": {
        "TFE_ADDRESS": "{env:TFE_ADDRESS}",
        "TFE_TOKEN": "{env:TFE_TOKEN}"
      }
    }
  }
}

[VERIFY: whether the README's nested mcp.servers form is accepted by the current OpenCode release].

Example prompts and what to expect

The reference page gives sample prompts. Here is how we read them.

A sensible workflow is to have the agent look up the provider version, read the docs for the resource, then write the HCL. You review the code and run terraform plan yourself. Keeping the plan step human is the cheapest safety you can buy.

Security notes

HashiCorp's README is blunt about several things.

• Data exposure. "Depending on the query, the MCP server may expose certain Terraform data to the MCP client and LLM." Do not use the server with untrusted clients or models.
• Output review. Recommendations are generated dynamically. Check them against your security, cost and compliance rules before applying.
• Third parties. The README says IBM is not responsible for third-party MCP clients or LLMs.
• Tokens. Use a scoped token. The server's get_token_permissions tool shows what the token can do, which is a quick way to check you did not paste an owner token.
• Destructive operations. Leave ENABLE_TF_OPERATIONS off until you have a reason.
• Central deployments. Never pass tokens in query parameters, because the server rejects those with a 400 error. Use TLS (MCP_TLS_CERT_FILE, MCP_TLS_KEY_FILE) and set MCP_ALLOWED_ORIGINS. TFE_ADDRESS can only be set on the server side, so a client cannot redirect your token to a hostile host. The MCP_ORGANIZATION_ALLOWLIST setting limits access to named HCP Terraform organizations.
• Custom instructions. The server reads default instructions from cmd/terraform-mcp-server/instructions.md. You can replace them with your own team practices and rebuild, or commit an AGENTS.md next to your Terraform code. The repository ships example files for both.

State files can hold secrets. The server's tools return workspace configuration, variables and state information, and anything it returns goes to the model provider. Mark sensitive variables as sensitive in HCP Terraform and avoid asking the agent to print them.

Limits and known issues

• The terraform toolset works only with HCP Terraform or Terraform Enterprise. If you keep state in an S3 bucket and run Terraform from a CI job, those tools have nothing to talk to. You still get the registry tools.
• It does not run the Terraform CLI, so it cannot plan a local directory.
• Corporate proxies that inspect TLS can break calls. The README has a troubleshooting section for Zscaler-style setups and a TFE_SKIP_TLS_VERIFY option, which we would avoid outside a test.
• .

Alternatives

Context7 can answer many "how do I write X" questions, but it indexes documentation sets. The Terraform server asks the registry directly and can fetch the latest version of a provider on demand, which is the point when the model's memory is stale.

Which agents it suits

Any agent that speaks MCP over stdio or HTTP can use it. Claude Code and Codex both have documented routes. Cursor, VS Code and OpenCode are in the README too. Antigravity works through its generic MCP config. If your client does not support elicitation, create_no_code_workspace may not behave as intended..

Our take

The registry half is an easy yes. It is read only, it needs no account, and it fixes a real weakness in how models write Terraform. If you only add one thing, add that, and start the server with --toolsets=registry.

The HCP Terraform half needs more thought. It is documented, careful and well fenced, with destructive actions behind a flag, tokens kept out of query strings and an allowlist for shared deployments. Still, the point of infrastructure as code is a reviewed plan. An agent that can create workspaces and trigger runs sits close to that line. We would give it a read-only team token first, watch what it asks for, and turn on ENABLE_TF_OPERATIONS only for a sandbox organization.

This is our reading of the documentation, not a hands-on test.

A short setup checklist

1. Install Docker and confirm it runs.
2. Add the server with --toolsets=registry and ask a provider question.
3. Pin the image to a version tag.
4. Create a read-only token for HCP Terraform and set TFE_TOKEN.
5. Call get_token_permissions and check the result matches what you meant to grant.
6. Leave ENABLE_TF_OPERATIONS unset.
7. Add an AGENTS.md with your team's module and naming rules.
8. Keep terraform plan and review as a human step.

For how this server fits next to others, see the MCP server list and best MCP servers.

Frequently asked questions

What does the Terraform MCP server do?

It lets an agent look up current provider and module documentation from the public registry and, with a token, manage HCP Terraform or Terraform Enterprise workspaces, projects, teams and runs.

Do I need a Terraform token?

Not for the registry tools. Private registry and workspace tools register only when TFE_TOKEN is set.

Can the agent apply or destroy things?

Only if you set ENABLE_TF_OPERATIONS to true. Deletes, force unlock and apply, discard or cancel on runs are gated by it.

Is it open source?

Yes. It is MPL-2.0 licensed Go code from HashiCorp.

Does it run terraform plan on my laptop?

No. It uses the public registry and the HCP Terraform or Enterprise API. It does not drive the local CLI.