Skip to content
MCP Shelf

Terraform MCP Server

View on GitHub

Current Terraform provider and module docs for your assistant, plus HCP Terraform if you want it.

  • Needs your setup first
  • ★ 1.6K GitHub stars
  • 543 downloads a week
  • Last commit 23 Oct 2026

What is Terraform MCP Server?

Terraform MCP Server is HashiCorp's server that gives an assistant current provider and module docs from the Terraform Registry, plus optional HCP Terraform workspaces and runs.

HashiCorp's own Terraform server looks things up in the public Terraform Registry so the model writes configuration against the provider version that exists today, not the one it remembers. It can search provider docs, read a resource's arguments, find modules and their inputs, and check the latest version of either. Policy libraries from the registry are searchable too.

With an HCP Terraform or Terraform Enterprise token it can go further: list and create workspaces, set variables and variable sets, start runs, and read plan and apply logs. Only the public registry tools are on by default. Tools that apply or discard runs, delete things or force-unlock a workspace stay off until you set ENABLE_TF_OPERATIONS.

Made by
HashiCorp (hashicorp/terraform-mcp-server)
Licence
MPL-2.0
GitHub stars
1.6K
Downloads
543 a week
Last commit
23 Oct 2026
Tools
61
Runs on
Your computer
Setup checked
27 Oct 2026
Page updated
27 Oct 2026

Our check: It needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 27 Oct 2026 we read its tools from the source code instead of running this config. The npm package called terraform-mcp-server is not published by HashiCorp. HashiCorp ships this server as a Docker image and a Go binary.

MCP Shelf take

Terraform needs something our Linux test machine does not have (an account, an app or a service), so on 27 Oct 2026 we read its source and counted 61 tools. 39 of the 61 only read; the other 22 can change things. Other directories point at a package with the same name that belongs to someone else; the config on this page installs the real one. It sits 5th of 5 in its category on our shelf by GitHub stars (1.6K, with 543 downloads a week).
MCP Shelf tests: numbers from our own runs, not the README · tested on 27 Oct 2026

What can Terraform MCP Server read and change?

It can read

  • Public provider, module and policy docs on registry.terraform.io
  • With a token: workspaces, variables, runs, plans, logs and state in your organisation

It can change

  • With a token: workspaces, projects, teams, variables, tags and new runs
  • With ENABLE_TF_OPERATIONS: applies and discards runs, deletes and unlocks

Safer setup: Run it without a token for registry lookups only. When you add a token, use one with read access, or a team token limited to the workspaces you want the model to see, and leave ENABLE_TF_OPERATIONS off.

What's in the pod

What tools does Terraform MCP Server have?

We found 61 tools in its source code on 27 Oct 2026. 39 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

How we tested it: Tool list read from the Go source of terraform-mcp-server (commit dca3a55). Only the 9 public registry tools load by default. The rest need an HCP Terraform or Terraform Enterprise token, and five of them also need ENABLE_TF_OPERATIONS.

Runs commands2 tools · Can start programs or run code.

ToolWhat it is for
action_runApplies, discards or cancels a run. Needs ENABLE_TF_OPERATIONS.
create_runStarts a plan in a workspace. Applying it needs action_run.

Changes things20 tools · Can create, edit, send or delete.

ToolWhat it is for
create_workspaceCreates a workspace.
create_workspace_variableAdds a variable to a workspace.
delete_workspace_safelyDeletes a workspace only if it manages no resources. Needs ENABLE_TF_OPERATIONS.
force_unlock_workspaceUnlocks a stuck workspace. Needs ENABLE_TF_OPERATIONS.
update_workspaceChanges a workspace's settings.
  • add_team_member
  • attach_policy_set_to_workspaces
  • attach_variable_set_to_workspaces
  • create_no_code_workspace
  • create_project
  • create_team
  • create_variable_in_variable_set
  • create_variable_set
  • create_workspace_tags
  • delete_project
  • delete_team
  • delete_variable_in_variable_set
  • detach_variable_set_from_workspaces
  • grant_team_access
  • update_workspace_variable

Only reads39 tools · Looks things up and changes nothing.

ToolWhat it is for
get_apply_logsReads the log of an apply.
get_latest_module_versionReturns the newest published version of a module.
get_latest_provider_versionReturns the newest published version of a provider.
get_module_detailsReads a module's inputs, outputs, dependencies and usage notes.
get_plan_json_outputReads a plan as structured JSON, resource by resource.
get_plan_logsReads the log of a plan.
get_policy_detailsReads one policy library and its rules.
get_private_module_detailsReads a private module's inputs, outputs and versions.
get_provider_capabilitiesSummarises what a provider offers: resources, data sources, functions and guides.
get_provider_detailsReads one provider doc page by its ID: arguments, attributes and examples.
get_run_detailsReads a run's status, plan and apply.
get_workspace_detailsReads a workspace's settings, variables and latest run.
list_runsLists the runs in a workspace, with filters.
list_state_versionsLists a workspace's state versions.
list_terraform_orgsLists the organisations the token can see.
list_variable_setsLists the variable sets in an organisation.
list_workspace_variablesLists a workspace's variables.
list_workspacesLists or searches the workspaces in an organisation.
search_modulesSearches the public registry for modules and returns IDs to look up.
search_policiesSearches the registry's policy libraries.
search_private_modulesSearches the private registry of your HCP Terraform or Terraform Enterprise organisation.
search_provider_docsFinds the provider doc pages for a service, such as a resource or data source, and returns their IDs.
whoamiShows which user or team the token belongs to.
  • get_apply_details
  • get_plan_details
  • get_private_provider_details
  • get_project
  • get_run_comments
  • get_sentinel_mock
  • get_stack_details
  • get_state_version
  • get_team
  • get_token_permissions
  • list_stacks
  • list_teams
  • list_terraform_projects
  • list_workspace_policy_sets
  • read_workspace_tags
  • search_private_providers

Tool groups

registry
The 9 public registry tools for providers, modules and policies. On by default and needs no token.
registry-private
Searching and reading private modules and providers in your organisation. Needs a token.
terraform
About 50 tools for organisations, projects, teams, workspaces, variables, runs, plans, applies, stacks and state. Needs a token.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

How do I install Terraform MCP Server?

Install steps from the Terraform MCP Server README

The project's own instructions, copied from its README on GitHub on 27 Oct 2026 under its MPL-2.0 licence. They are the source of truth; the ready-made configs further down are built from them. The rest of the README is in the README tab.

Installation
Usage with Visual Studio Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

More about using MCP server tools in VS Code's agent mode documentation.

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

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

Optionally, you can add a similar example (i.e. without the mcp key) to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

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

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}
Usage with Cursor

Add this to your Cursor config (~/.cursor/mcp.json) or via Settings → Cursor Settings → MCP:

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ]
    }
  }
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}
Usage with Claude Desktop / Amazon Q Developer / Kiro CLI

More about using MCP server tools in Claude Desktop user documentation. Read more about using MCP server in Amazon Q Developer and Kiro CLI.

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ]
    }
  }
}

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

More about using and adding MCP server tools in Claude Code user documentation

  • Local (stdio) Transport
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Remote (streamable-http) Transport
# Run server (example)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp
Usage with Codex CLI

More about using and adding MCP server tools in Codex CLI user documentation.

Note: Add TFE_ADDRESS and TFE_TOKEN to the Docker commands for authenticated HCP Terraform or Terraform Enterprise tools.

  • Local (stdio) Transport
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server
  • Remote (streamable-http) Transport
# Run server (example)
docker run --rm -p 127.0.0.1:8080:8080 -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Codex
codex mcp add terraform --url http://localhost:8080/mcp
Usage with Gemini extensions

For security, avoid hardcoding your credentials, create or update ~/.gemini/.env (where ~ is your home or project directory) for storing HCP Terraform or Terraform Enterprise credentials

# ~/.gemini/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

Install the extension & run Gemini

gemini extensions install https://github.com/hashicorp/terraform-mcp-server
gemini
Usage with Bob IDE / Shell

More about using and adding MCP servers tools in Bob IDE or Shell Using MCP in Bob.

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ],
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ],
      "disabled": false
    }
  }
}
Kubernetes (Helm)

A Helm chart for deploying the server on Kubernetes is available under helm/terraform-mcp-server.

Install from source

Use the latest release version:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest

Use the main branch:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server",
        "env": {
          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"
        },
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server"
      }
    }
  }
}

What you need first

  • Docker, or Go to install the binary yourself
  • Nothing else for the public registry tools
  • An HCP Terraform or Terraform Enterprise API token for workspace and run tools

Add Terraform MCP Server to your app

Pick your app for a ready-to-paste snippet and where it goes, built from the steps above.

Where it goes: Your terminal

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

This adds it for every project with the public registry tools. For HCP Terraform, add -e TFE_TOKEN=your-token before the image name and --toolsets=all after it.

This starts the public registry tools only. For HCP Terraform, add "-e", "TFE_TOKEN" (and "-e", "TFE_ADDRESS" for Terraform Enterprise) before the image name, put the values in "env", and pass --toolsets=all after the image. Without Docker, run go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest and use "terraform-mcp-server" with the argument "stdio".

Checked against the project's own install docs on 27 Oct 2026: hashicorp/terraform-mcp-server README, developer.hashicorp.com/terraform/mcp-server.

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Terraform MCP Server not working? Common fixes

Certificate errors behind a corporate proxy such as Zscaler
Mount your company's CA certificate into the container and point SSL_CERT_FILE at it, or install it in the system store if you run the binary.
Only registry tools show up
That is the default. Pass --toolsets=all after the image name and set TFE_TOKEN.
The apply and delete tools are missing
They load only when ENABLE_TF_OPERATIONS is true, as well as a token being set.
docker: command not found in the client log
Install Docker Desktop and make sure it is running, or install the Go binary and use terraform-mcp-server stdio instead.

How do I configure Terraform MCP Server?

Names are exactly as the project spells them. Required ones are marked.

SettingWhat it does
--toolsetsCommand line flagWhich groups of tools to load: registry, registry-private, terraform, all or default. Default is registry only.--toolsets=registry,terraform
--toolsCommand line flagLoad named tools instead of whole groups. Cannot be combined with --toolsets.--tools=search_modules,get_module_details
TFE_TOKENEnvironment variableAn HCP Terraform or Terraform Enterprise API token. Needed for every tool outside the public registry.
TFE_ADDRESSEnvironment variableThe address of your Terraform Enterprise install, with https://. Leave it unset for HCP Terraform.https://tfe.example.com
ENABLE_TF_OPERATIONSEnvironment variableSet to true to load the tools that apply or discard runs, delete projects, teams or workspaces, and force an unlock.true
TFE_SKIP_TLS_VERIFYEnvironment variableSkips certificate checks against Terraform Enterprise. Only for a test install with a self-signed certificate.
TRANSPORT_MODEEnvironment variableSet to streamable-http to serve over HTTP instead of stdio. TRANSPORT_HOST and TRANSPORT_PORT set where it listens.streamable-http

Terraform MCP Server FAQ

How do I add the Terraform MCP Server to Claude Code?

With Docker running, run claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server:1.4.1. That gives the registry tools in every project.

How do I use the Terraform MCP Server in Cursor or VS Code?

Add an entry that runs docker run -i --rm with the hashicorp/terraform-mcp-server image. For HCP Terraform, pass TFE_TOKEN into the container and add --toolsets=all after the image name.

Do I need an HCP Terraform account?

No. The public registry tools work with no account and no token. A token only adds the workspace, variable and run tools.

Can the Terraform MCP Server run terraform plan on my laptop?

No. It does not run the Terraform CLI locally. Runs it starts happen in HCP Terraform or Terraform Enterprise, and it reads their plan and apply logs.

Can it apply or destroy infrastructure?

Only if you allow it. Applying or discarding runs, deleting workspaces and force-unlocking stay off until ENABLE_TF_OPERATIONS is true and a token is set.

Is the npm package called terraform-mcp-server the same thing?

No. HashiCorp publishes this server as a Docker image and a Go binary, not on npm. Use the hashicorp/terraform-mcp-server image.

Does it work with ChatGPT?

Not directly. It runs on your machine, and ChatGPT only connects to remote servers by URL. HashiCorp documents an HTTP mode for hosting it yourself, but that needs your own public endpoint.

Is the Terraform MCP Server free?

Yes. The server is open source under MPL-2.0. HCP Terraform, if you connect it, has its own plans.

Terraform MCP Server README

This is the project's own README from hashicorp/terraform-mcp-server, written by HashiCorp (hashicorp/terraform-mcp-server), and shared under its MPL-2.0 licence. We copied it on 27 Oct 2026, so the version on GitHub may be newer.

Terraform MCP Server

The Terraform MCP Server is a Model Context Protocol (MCP) server that integrates seamlessly with Terraform Registry and HCP Terraform APIs, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

Table of Contents

Get started Client integrations Build and run
Features
Prerequisites
Command Line Options
Instructions 		Installation
Visual Studio Code
Cursor
Claude Desktop, Amazon Q Developer, and Kiro CLI
Claude Code
Codex CLI
Gemini extensions
Bob IDE and Shell 		Install from source
Building the Docker Image locally
Transport Support
Stdio Transport
StreamableHTTP Transport
Server capabilities Deployment and security Help and contributing
Available Tools
Available Resources
Available Metrics
Tool Filtering 		Session Modes
Token Passthrough for Centralized Deployments
Client IP Forwarding
Trust model
Trusted hops
Limitations
Migrating from earlier versions
Supported Headers
Security Considerations
Centralized Deployment Example 		Troubleshooting
Corporate Proxy and TLS Inspection
Development
Contributing
License
Security
Support

Features

  • Dual Transport Support: Both Stdio and StreamableHTTP transports with configurable endpoints
  • Terraform Registry Integration: Direct integration with public Terraform Registry APIs for providers, modules, and policies
  • HCP Terraform & Terraform Enterprise Support: Full workspace management, organization/project listing, and private registry access
  • Workspace Operations: Create, update, delete workspaces with support for variables, tags, and run management
  • OTel metrics for monitoring tool usage: Integration with open telemetry meters to track tool-call volume, latency and failures in Streamable HTTP mode. Also exposes default http server metrics when this feature is enabled

Security Note: Depending on the query, the MCP server may expose certain Terraform data to the MCP client and LLM. Do not use the MCP server with untrusted MCP clients or LLMs.

Legal Note: Your use of a third party MCP Client/LLM is subject solely to the terms of use for such MCP/LLM, and IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP Clients/LLMs, and may not be able to provide support to resolve issues which are caused by the third party tools.

Caution: The outputs and recommendations provided by the MCP server are generated dynamically and may vary based on the query, model, and the connected MCP client. Users should thoroughly review all outputs/recommendations to ensure they align with their organization’s security best practices, cost-efficiency goals, and compliance requirements before implementation.

Prerequisites

  1. Ensure Docker is installed and running to use the server in a containerized environment.
  2. Install an AI assistant that supports the Model Context Protocol (MCP).

Command Line Options

Environment Variables:

Variable Description Default
TFE_ADDRESS Sets the Terraform Enterprise/HCP Terraform address for API calls. Must include the protocol (e.g., https://app.terraform.io). In streamable-http mode this is the only way to set the address; it cannot be supplied by clients via header or query parameter. Optional
TFE_TOKEN Terraform Enterprise API token "" (empty)
TF_MCP_SHARED_SECRET Shared secret sent as the X-Tf-Mcp-Secret header on requests to HCP Terraform / TFE, used to identify requests originating from a hosted MCP deployment. Should only be used over TLS. "" (empty)
TFE_SKIP_TLS_VERIFY Skip HCP Terraform or Terraform Enterprise TLS verification false
LOG_LEVEL Logging level: trace, debug, info, warn, error, fatal, panic (overrides --log-level flag) info
LOG_FORMAT Logging format: text or json (overrides --log-format flag) text
TRANSPORT_MODE Set to streamable-http to enable HTTP transport (legacy http value still supported) stdio
TRANSPORT_HOST Host to bind the HTTP server 127.0.0.1
TRANSPORT_PORT HTTP server port 8080
MCP_ENDPOINT HTTP server endpoint path /mcp
MCP_REDIRECT_ROOT_URL URL to redirect requests to / to ""
MCP_KEEP_ALIVE Keep-alive interval for SSE connections (e.g., 30s, 1m). 0 to disable 0
MCP_SESSION_MODE Session mode: stateful or stateless stateful
MCP_ALLOWED_ORIGINS Comma-separated list of allowed origins for CORS "" (empty)
MCP_CORS_MODE CORS mode: strict, development, or disabled strict
MCP_TLS_CERT_FILE Path to TLS cert file, required for non-localhost deployment (e.g. /path/to/cert.pem) "" (empty)
MCP_TLS_KEY_FILE Path to TLS key file, required for non-localhost deployment (e.g. /path/to/key.pem) "" (empty)
MCP_RATE_LIMIT_GLOBAL Global rate limit (format: rps:burst) 10:20
MCP_RATE_LIMIT_SESSION Per-session rate limit (format: rps:burst) 5:10
MCP_ORGANIZATION_ALLOWLIST CSV list of HCP Terraform organization names allowed to access the HTTP server "" (empty)
MCP_FORWARD_CLIENT_IP Forward the client IP to HCP Terraform / TFE via X-Forwarded-For. Set to true to enable false
MCP_REMOTE_IP_METHOD How the client IP is sourced when forwarding is enabled: RemoteAddr (direct connection only), X-Real-IP, or X-Forwarded-For RemoteAddr
MCP_XFF_TRUSTED_HOPS Number of trusted proxy hops counted from the right of the X-Forwarded-For chain. Only used when MCP_REMOTE_IP_METHOD=X-Forwarded-For 0
ENABLE_TF_OPERATIONS Enable tools that require explicit approval false
OTEL_METRICS_ENABLED Enable tools and server metrics using otel false
OTEL_METRICS_SERVICE_VERSION Version of the terraform-mcp-server sending metrics, which is used to set metric attributes. It also helps track metrics across different deployments latest
OTEL_METRICS_SERVICE_NAME Identifies the source of the metrics (e.g., "terraform-mcp-server") terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVAL Controls the frequency of metric flushes 2
OTEL_METRICS_ENDPOINT URL of your OTel Collector or backend localhost:4318
INSTANA_ENABLED Enable Instana instrumentation (metrics and HTTP request tracing) for the streamable-http server. Requires an Instana agent that is reachable by the server. false
INSTANA_SERVICE_NAME If Instana instrumentation is enabled, the service name to use for the MCP server terraform-mcp-server 
# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--organization-allowlist <orgs-csv>] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

Instructions

Default instructions for the MCP server is located in cmd/terraform-mcp-server/instructions.md, if those do not seem appropriate for your organization's Terraform practices or if the MCP server is producing inaccurate responses, please replace them with your own instructions and rebuild the container or binary. An example of such instruction is located in instructions/example-mcp-instructions.md

AGENTS.md essentially behaves as READMEs for coding agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project. One AGENTS.md file works with different coding agents. An example of such instruction is located in instructions/example-AGENTS.md, in order to use it commit a file name AGENTS.md to the directory where your Terraform configurations reside.

Installation

Usage with Visual Studio Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

More about using MCP server tools in VS Code's agent mode documentation.

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

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

Optionally, you can add a similar example (i.e. without the mcp key) to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

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

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}
Usage with Cursor

Add this to your Cursor config (~/.cursor/mcp.json) or via Settings → Cursor Settings → MCP:

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ]
    }
  }
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}
Usage with Claude Desktop / Amazon Q Developer / Kiro CLI

More about using MCP server tools in Claude Desktop user documentation. Read more about using MCP server in Amazon Q Developer and Kiro CLI.

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ]
    }
  }
}

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

More about using and adding MCP server tools in Claude Code user documentation

  • Local (stdio) Transport
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
  • Remote (streamable-http) Transport
# Run server (example)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp
Usage with Codex CLI

More about using and adding MCP server tools in Codex CLI user documentation.

Note: Add TFE_ADDRESS and TFE_TOKEN to the Docker commands for authenticated HCP Terraform or Terraform Enterprise tools.

  • Local (stdio) Transport
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server
  • Remote (streamable-http) Transport
# Run server (example)
docker run --rm -p 127.0.0.1:8080:8080 -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Codex
codex mcp add terraform --url http://localhost:8080/mcp
Usage with Gemini extensions

For security, avoid hardcoding your credentials, create or update ~/.gemini/.env (where ~ is your home or project directory) for storing HCP Terraform or Terraform Enterprise credentials

# ~/.gemini/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

Install the extension & run Gemini

gemini extensions install https://github.com/hashicorp/terraform-mcp-server
gemini
Usage with Bob IDE / Shell

More about using and adding MCP servers tools in Bob IDE or Shell Using MCP in Bob.

Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ],
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ],
      "disabled": false
    }
  }
}
Kubernetes (Helm)

A Helm chart for deploying the server on Kubernetes is available under helm/terraform-mcp-server.

Install from source

Use the latest release version:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest

Use the main branch:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
Version 0.3.0+ or greaterVersion 0.2.3 or lower
{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server",
        "env": {
          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"
        },
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server"
      }
    }
  }
}

Building the Docker Image locally

Before using the server, you need to build the Docker image locally:

  1. Clone the repository:
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Build the Docker image:
make docker-build
  1. This will create a local Docker image that you can use in the following configuration.
# Run in stdio mode
docker run -i --rm terraform-mcp-server:dev

# Run in streamable-http mode
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# Filter tools (optional)
docker run -i --rm terraform-mcp-server:dev --toolsets=registry,terraform
docker run -i --rm terraform-mcp-server:dev --tools=search_provider_docs,get_provider_details

Note: When running in Docker, you should set TRANSPORT_HOST=0.0.0.0 to allow connections from outside the container.

  1. (Optional) Test connection in http mode
# Test the connection
curl http://localhost:8080/health
  1. You can use it on your AI assistant as follow:
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Available Tools

Check out available tools here :link:

Available Resources

Check out available resources here :link:

Available Metrics

Two kinds of metrics are collected. First, standard HTTP server metrics are added by wrapping the HTTP mux with otelhttp.NewHandler(...). This emits:

  1. http.server.request.body.size
  2. http.server.response.body.size
  3. http.server.request.duration

Second, the MCP server records custom tool metrics around tool execution using MCP hooks (BeforeCallTool / AfterCallTool). These emit:

  1. mcp_tool_calls_total
  2. mcp_tool_errors_total
  3. mcp_tool_duration_seconds
Tool Filtering

Control which tools are available using --toolsets (groups) or --tools (individual):

# Enable tool groups (default: registry)
terraform-mcp-server --toolsets=registry,terraform

# Enable specific tools only
terraform-mcp-server --tools=search_provider_docs,get_provider_details,list_workspaces

Available toolsets: registry, registry-private, terraform, all, default. See pkg/toolsets/mapping.go for individual tool names. Cannot use both flags together.

Transport Support

The Terraform MCP Server supports multiple transport protocols:

1. Stdio Transport (Default)

Standard input/output communication using JSON-RPC messages. Ideal for local development and direct integration with MCP clients.

2. StreamableHTTP Transport

Modern HTTP-based transport supporting both direct HTTP requests and Server-Sent Events (SSE) streams. This is the recommended transport for remote/distributed setups.

Features:

  • Endpoint: http://{hostname}:8080/mcp
  • Health Check: http://{hostname}:8080/health
  • Environment Configuration: Set TRANSPORT_MODE=http or TRANSPORT_PORT=8080 to enable
  • Organization Allowlist: Set MCP_ORGANIZATION_ALLOWLIST or --organization-allowlist to a CSV list of allowed HCP Terraform organization names

Session Modes

The Terraform MCP Server supports two session modes when using the StreamableHTTP transport:

  • Stateful Mode (Default): Maintains session state between requests, enabling context-aware operations.
  • Stateless Mode: Each request is processed independently without maintaining session state, which can be useful for high-availability deployments or when using load balancers.

To enable stateless mode, set the environment variable:

export MCP_SESSION_MODE=stateless

Token Passthrough for Centralized Deployments

When running the MCP server centrally (StreamableHTTP mode) for multiple users, each user can pass their own Terraform token via HTTP headers for RBAC enforcement. This allows a single server instance to serve multiple users with different permissions.

When MCP_ORGANIZATION_ALLOWLIST or --organization-allowlist is configured, the allowlist must be a CSV list of HCP Terraform organization names. The server requires Authorization: Bearer <token> and rejects requests unless that token can access at least one organization in the CSV allowlist. The bearer token takes precedence if the request also includes a TFE_TOKEN header, ensuring the token validated by the allowlist is the token used for Terraform API requests. Organization name matching is case-insensitive. If the configured CSV value parses to zero organization names, the server exits with a malformed organization allowlist error.

Client IP Forwarding

When running the MCP server centrally behind a proxy or load balancer, you can forward the originating client's IP to HCP Terraform / TFE via the X-Forwarded-For header. This is off by default and must be enabled with MCP_FORWARD_CLIENT_IP=true.

When enabled, the server sources the client IP according to MCP_REMOTE_IP_METHOD:

Method Behavior
RemoteAddr (default) Uses only the address of the direct TCP connection. Ignores X-Forwarded-For and X-Real-IP.
X-Real-IP Uses the X-Real-IP header if it is a valid IP, otherwise falls back to RemoteAddr.
X-Forwarded-For Uses the X-Forwarded-For header, selecting the entry MCP_XFF_TRUSTED_HOPS positions from the right. Falls back to RemoteAddr if the value is missing or invalid.
Trust model

X-Forwarded-For and X-Real-IP are set by clients and intermediary proxies, so they can be spoofed unless a trusted proxy in front of the server overwrites them. For this reason the default is RemoteAddr, which trusts only the peer the server is directly connected to. Only enable X-Real-IP or X-Forwarded-For when the server sits behind a proxy you control that sets these headers. Some load balancers, including AWS Application Load Balancers, do not set X-Real-IP, so with those the header comes straight from the client and should not be used.

Trusted hops

When using X-Forwarded-For, set MCP_XFF_TRUSTED_HOPS to the number of proxies you operate in front of the server. Each proxy appends the address it received the request from, not its own address, so the client IP is the entry that many positions from the right. Everything to the left of it was sent by the client and can be spoofed.

For example, behind a single load balancer such as an AWS ALB, set MCP_XFF_TRUSTED_HOPS=1. A header of 198.51.100.7 resolves to 198.51.100.7, and a header of 1.2.3.4, 198.51.100.7, where the client sent 1.2.3.4 itself, also resolves to 198.51.100.7. With MCP_XFF_TRUSTED_HOPS=2 and 1.2.3.4, 198.51.100.7, 10.0.0.5, the server selects 198.51.100.7. If the hop count is greater than the number of entries, or the selected entry is not a valid IP, the server falls back to RemoteAddr.

Setting the hop count too high will trust a client-supplied value; setting it too low will select an address from your own infrastructure. Set it to the exact number of proxies you run.

Limitations
  • If a request carries multiple X-Forwarded-For headers, the server joins them in order before selecting an entry. X-Forwarded-For header.
  • IPv4 and IPv6 addresses are both supported. Values that are not valid IPs are rejected and the server falls back to RemoteAddr.
Migrating from earlier versions

Earlier versions used the leftmost X-Forwarded-For value when the header was present, with no configuration. This was insecure, since the leftmost value is the most easily spoofed. The default is now RemoteAddr. If you run the server behind a proxy and rely on X-Forwarded-For being forwarded to HCP Terraform / TFE, set MCP_REMOTE_IP_METHOD=X-Forwarded-For and MCP_XFF_TRUSTED_HOPS to the number of proxies you operate.

Supported Headers
Header Description
TFE_TOKEN Terraform API token
Authorization: Bearer <token> Alternative method using standard Bearer auth
TFE_SKIP_TLS_VERIFY Skip TLS verification for the request
Example: curl
# Using TFE_TOKEN header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "TFE_TOKEN: your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

# Using Authorization Bearer header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'
Security Considerations
  • TFE_ADDRESS cannot be set by clients. In streamable-http mode the Terraform address is sourced only from the server-side TFE_ADDRESS environment variable (or the default). Requests that attempt to set TFE_ADDRESS via HTTP header or query parameter are rejected with a 403. This prevents a client from redirecting requests, and the Authorization token, to a malicious server.
  • Hosted deployment identification: setting TF_MCP_SHARED_SECRET sends that value as the X-Tf-Mcp-Secret header on every HCP Terraform / TFE request, letting the backend identify requests from a known hosted deployment (e.g. to apply IP allowlists). It is a static secret sent in a header, so only use it over TLS and treat the value as a credential.
  • Never pass tokens in query parameters - the server will reject such requests with a 400 error.
  • Always use TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) when deploying centrally to protect tokens in transit.
  • Configure MCP_ALLOWED_ORIGINS to restrict which clients can connect.
Centralized Deployment Example
# Start server centrally (no token set server-side)
docker run -p 8080:8080 \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e TFE_ADDRESS=https://tfe.company.com \
  -e MCP_TLS_CERT_FILE=/certs/server.pem \
  -e MCP_TLS_KEY_FILE=/certs/server-key.pem \
  -e MCP_ALLOWED_ORIGINS=https://ide.company.com \
  -e MCP_ORGANIZATION_ALLOWLIST=team-alpha,team-beta \
  -v /path/to/certs:/certs \
  hashicorp/terraform-mcp-server:1.4.1

Users then connect with their individual tokens passed via headers, enabling per-user RBAC enforcement.

Troubleshooting

Corporate Proxy / TLS Inspection (Zscaler, etc.)

If you're behind a corporate proxy that performs TLS inspection (like Zscaler Internet Access), you may see certificate errors:

tls: failed to verify certificate: x509: certificate signed by unknown authority

Solution: Mount your corporate CA certificate into the container:

docker run -i --rm \
  -v /path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem \
  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
  hashicorp/terraform-mcp-server:1.4.1

For MCP client configurations:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem",
        "-e", "SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem",
        "-e", "TFE_TOKEN=<>",
        "hashicorp/terraform-mcp-server:1.4.1"
      ]
    }
  }
}

Alternative: Run the binary directly

If Docker is not permitted in your environment, you can install and run the server binary directly, which will use your system's certificate store:

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
terraform-mcp-server stdio

Development

Prerequisites
  • Go (check go.mod file for specific version)
  • Docker (optional, for container builds)
Available Make Commands
Command Description
make build Build the binary
make test Run all tests
make test-e2e Run end-to-end tests
make docker-build Build Docker image
make run-http Run HTTP server locally
make docker-run-http Run HTTP server in Docker
make test-http Test HTTP health endpoint
make clean Remove build artifacts
make help Show all available commands

Contributing

  1. Fork the repository
  2. Create your feature branch
  3. Make your changes
  4. Run tests
  5. Submit a pull request

License

This project is licensed under the terms of the MPL-2.0 open source license. Please refer to LICENSE file for the full terms.

Security

For security issues, please contact security@hashicorp.com or follow our security policy.

Support

For bug reports and feature requests, please open an issue on GitHub.

For general questions and discussions, open a GitHub Discussion.

Two peas, one chat

Chat with AI about Terraform

Opens a chat primed with Terraform’s README and setup docs from this page, or add it in Cursor to use its tools.

The Cursor button opens Cursor and asks before it adds the server. Fill in any keys it needs in Cursor’s MCP settings.

Peas in a pod

What are the alternatives to Terraform MCP Server?

How Terraform MCP Server lines up against its neighbours on the shelf. See every cloud and operations server.

  • Terraform MCP ServerThis pea

    Current Terraform provider and module docs for your assistant, plus HCP Terraform if you want it.

    Tools
    61
    Runs on
    Your computer
    Licence
    MPL-2.0
    Stars
    1.6K

  • AWS Knowledge MCP Server

    AWS's free hosted server for current AWS docs, API references and region checks.

    Tools
    5
    Runs on
    Hosted
    Licence
    Apache-2.0
    Stars
    9.8K

  • Cloudflare MCP Servers

    Cloudflare's own hosted servers, starting with a docs search that needs no sign-in.

    Tools
    2
    Runs on
    Hosted
    Licence
    Apache-2.0
    Stars
    4.4K

  • Grafana MCP

    Dashboards, metrics, logs, alerts and incidents from your Grafana, in one server.

    Tools
    62
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    3.6K

  • Azure DevOps MCP

    Microsoft's server for Azure DevOps boards, repos, pipelines, wikis and test plans.

    Tools
    44
    Runs on
    Hosted or your computer
    Licence
    MIT
    Stars
    2.1K
Full docs on GitHubhashicorp/terraform-mcp-server

Something wrong on this page? Tell us.