Terraform

[Image] 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

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:

# Stdio modeterraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]
# StreamableHTTP modeterraform-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.

{  "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": {        "type": "http",        "url": "https://mcp.terraform.io/mcp",        "headers": {          "Authorization": "Bearer <<TFE_TOKEN>>"        }      }    }  }}

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.

{  "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": {      "type": "http",      "url": "https://mcp.terraform.io/mcp",      "headers": {        "Authorization": "Bearer <<TFE_TOKEN>>"      }    }  }}

[Install in VS Code (docker)] [Install in VS Code Insiders (docker)]

Usage with Cursor

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

{  "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": {      "url": "https://mcp.terraform.io/mcp",      "headers": {        "Authorization": "Bearer <<TFE_TOKEN>>"      }    }  }}

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.

{  "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": {      "url": "https://mcp.terraform.io/mcp",      "headers": {        "Authorization": "Bearer <<TFE_TOKEN>>"      }    }  }}

NOTE: Claude Desktop does not support configuring remote MCP servers via configuration file, use Custom Connectors instead.

Usage with Claude Code

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

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

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

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

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

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/.envTFE_ADDRESS=your_tfe_address_hereTFE_TOKEN=your_tfe_token_here

Install the extension & run Gemini

gemini extensions install https://github.com/hashicorp/terraform-mcp-servergemini

Usage with Bob IDE / Shell

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

{  "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": {      "url": "https://mcp.terraform.io/mcp",      "headers": {        "Authorization": "Bearer <<TFE_TOKEN>>"      },      "disabled": false    }  }}

Usage with OpenCode

More about using and adding MCP servers in OpenCode user documentation. Add the server to your project opencode.json or the global ~/.config/opencode/opencode.json.

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "servers": {      "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}"        }      }    }  }}

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "servers": {      "terraform": {        "type": "remote",        "url": "https://mcp.terraform.io/mcp",        "oauth": false,        "headers": {          "Authorization": "Bearer <<TFE_TOKEN>>"        }      }    }  }}

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

{  "mcp": {    "servers": {      "terraform": {        "type": "stdio",        "command": "/path/to/terraform-mcp-server",        "env": {          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"        }      }    }  }}

{  "mcp": {    "servers": {      "terraform": {        "type": "http",        "url": "https://mcp.terraform.io/mcp",        "headers": {          "Authorization": "Bearer <<TFE_TOKEN>>"        }      }    }  }}

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.gitcd terraform-mcp-server

2. Build the Docker image:

make docker-build

3. This will create a local Docker image that you can use in the following configuration.

# Run in stdio modedocker run -i --rm terraform-mcp-server:dev
# Run in streamable-http modedocker 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,terraformdocker 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.

4. (Optional) Test connection in http mode

# Test the connectioncurl http://localhost:8080/health

5. 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
4. mcp_client_type_total
5. mcp_org_tool_calls_total

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 onlyterraform-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.

Search Toolset

Search tools resolve a proposed source from explicit arguments first, then server-configured query defaults. Without an override, the source workspace uses TF_MCP_QUERY_WORKSPACE, then TF_WORKSPACE, and the source organization uses TF_CLOUD_ORGANIZATION. Import tools independently resolve a proposed target workspace from an explicit argument, then TF_MCP_IMPORT_WORKSPACE, then TF_WORKSPACE; they never use TF_MCP_QUERY_WORKSPACE as the target default. The target organization uses an explicit argument, then TF_CLOUD_ORGANIZATION, and must still match the QueryRun source organization. Overrides apply independently to each field. If either field was omitted, present and confirm the complete resolved pair before continuing. Empty and whitespace-only values are treated as unset. No TF_MCP_ORGANIZATION variable is used.

On a remote server, these environment variables are server-wide defaults shared by all users of that server. Explicit terraform_org_name and workspace_name arguments override the corresponding defaults for that request; they do not change the server configuration or other users' requests. organization_name is not accepted as a Search tool input alias.

When either scope field is omitted, the Mark3Labs route returns a normal, non-error JSON result with status (input_required), proposed_scope, and missing_inputs before tool-handler client acquisition or scoped API access. The agent presents the complete proposal, obtains confirmation or corrections, and retries with explicit terraform_org_name and workspace_name. The official SDK route requests the same complete pair through CallToolResult.InputRequests. Both routes require explicit scope on the continued call and make no scoped API request while requesting input.

Source confirmation and query execution approval: Before provider discovery for a new query, the agent confirms the resolved source organization and workspace. Before calling execute_query, the agent separately summarizes that source and the query selections (provider, resource types, and filters, if any), explains that execution starts a query run without creating or modifying infrastructure, and waits for user approval. If the source or query selections change, approval must be obtained again. This is agent-driven guidance, not a server-enforced approval parameter or status; clients calling the tool directly are not blocked by an approval check.

Pass workspace variables to the MCP server process, for example through the environment settings in OpenCode's JSON/JSONC configuration or an equivalent MCP-client configuration. A container or remote deployment must receive them in its own environment. The server does not read client configuration files or inherit the agent's separate shell environment. When import is requested, the agent always asks for and confirms the target organization, target workspace, and existing local configuration directory. A query default or configured import default never authorizes that target. After confirmation, pass the complete target explicitly to prepare_import and verify_import_plan. The read-only import tools do not upload configuration, create a speculative Run, apply an import, or modify infrastructure.

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:

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

Example: curl

# Using TFE_TOKEN headercurl -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 headercurl -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",...}'

Request IDs

In streamable-http mode every request gets its own correlation ID. The server sends it as the X-Request-Id header on its calls to HCP Terraform / TFE and the public registry, returns it to the client in the X-Request-Id response header, and logs it as request_id on tool calls. In stdio mode each tool call gets its own ID. The server always generates the ID itself, so an X-Request-Id sent by the client is ignored.

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.
• TFE_SKIP_TLS_VERIFY cannot be set by clients. In streamable-http mode it is read only from the server-side environment variable. If a client sends it as a header or query parameter it is ignored and a warning is logged, so a client cannot turn off certificate verification on the server's calls to HCP Terraform / TFE.
• 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.

Profiling

Set MCP_PPROF_ADDR to serve Go's pprof endpoints on a separate port from the MCP server. It's off by default and works in every transport mode.

MCP_PPROF_ADDR=127.0.0.1:6060 TRANSPORT_MODE=streamable-http terraform-mcp-server

Then grab a profile with go tool pprof:

# 30 second CPU profilego tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30
# memory in use right nowgo tool pprof http://127.0.0.1:6060/debug/pprof/heap
# every goroutine and what it's doingcurl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1

http://127.0.0.1:6060/debug/pprof/ lists everything you can grab. Profiles show the server's internals, so keep it on loopback, the server logs a warning if it's bound to anything else. In Kubernetes, bind it to 127.0.0.1 and use kubectl port-forward pod/<pod> 6060:6060 to get to it.

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@latestterraform-mcp-server stdio

Development

Prerequisites

• Go (check go.mod file for specific version)
• Docker (optional, for container builds)

Available Make 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 [email protected] 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.