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.
Generate more accurate Terraform and automate workflows for HCP Terraform and Terraform Enterprise
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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
Ensure Docker is installed and running to use the server in a containerized environment.
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
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
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).
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.
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
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.
Two kinds of metrics are collected.
First, standard HTTP server metrics are added by wrapping the HTTP mux with otelhttp.NewHandler(...). This emits:
http.server.request.body.size
http.server.response.body.size
http.server.request.duration
Second, the MCP server records custom tool metrics around tool execution using MCP hooks (BeforeCallTool / AfterCallTool). These emit:
mcp_tool_calls_total
mcp_tool_errors_total
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: