Terraform MCP Server

1# <img src="public/images/Terraform-LogoMark_onDark.svg" width="30" align="left" style="margin-right: 12px;"/> Terraform MCP Server
2 
3The Terraform MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
4server that provides seamless integration with Terraform Registry APIs, enabling advanced
5automation and interaction capabilities for Infrastructure as Code (IaC) development.
6 
7## Features
8 
9- **Dual Transport Support**: Both Stdio and StreamableHTTP transports with configurable endpoints
10- **Terraform Registry Integration**: Direct integration with public Terraform Registry APIs for providers, modules, and policies
11- **HCP Terraform & Terraform Enterprise Support**: Full workspace management, organization/project listing, and private registry access
12- **Workspace Operations**: Create, update, delete workspaces with support for variables, tags, and run management
13 
14> **Security Note:** At this stage, the MCP server is intended for local use only. If using the StreamableHTTP transport, always configure the MCP_ALLOWED_ORIGINS environment variable to restrict access to trusted origins only. This helps prevent DNS rebinding attacks and other cross-origin vulnerabilities.
15 
16> **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.
17 
18> **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.
19 
20> **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.
21 
22## Prerequisites
23 
241. Ensure [Docker](https://www.docker.com/) is installed and running to use the server in a containerized environment.
251. Install an AI assistant that supports the Model Context Protocol (MCP).
26 
27## Command Line Options
28 
29**Environment Variables:**
30 
31| Variable | Description | Default |
32|----------|-------------|---------|
33| `TFE_ADDRESS` | HCP Terraform or TFE address | `"https://app.terraform.io"` |
34| `TFE_TOKEN` | Terraform Enterprise API token | `""` (empty) |
35| `TFE_SKIP_TLS_VERIFY` | Skip HCP Terraform or Terraform Enterprise TLS verification | `false` |
36| `TRANSPORT_MODE` | Set to `streamable-http` to enable HTTP transport (legacy `http` value still supported) | `stdio` |
37| `TRANSPORT_HOST` | Host to bind the HTTP server | `127.0.0.1` |
38| `TRANSPORT_PORT` | HTTP server port | `8080` |
39| `MCP_ENDPOINT` | HTTP server endpoint path | `/mcp` |
40| `MCP_SESSION_MODE` | Session mode: `stateful` or `stateless` | `stateful` |
41| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS | `""` (empty) |
42| `MCP_CORS_MODE` | CORS mode: `strict`, `development`, or `disabled` | `strict` |
43| `MCP_TLS_CERT_FILE` | Path to TLS cert file, required for non-localhost deployment (e.g. `/path/to/cert.pem`) | `""` (empty) |
44| `MCP_TLS_KEY_FILE` |  Path to TLS key file, required for non-localhost deployment (e.g. `/path/to/key.pem`)| `""` (empty) |
45| `MCP_RATE_LIMIT_GLOBAL` | Global rate limit (format: `rps:burst`) | `10:20` |
46| `MCP_RATE_LIMIT_SESSION` | Per-session rate limit (format: `rps:burst`) | `5:10` |
47| `ENABLE_TF_OPERATIONS` | Enable tools that require explicit approval | `false` |
48 
49```bash
50# Stdio mode
51terraform-mcp-server stdio [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]
52 
53# StreamableHTTP mode
54terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]
55```
56 
57## Instructions
58 
59Default 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`
60 
61`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.
62 
63## Installation
64 
65### Usage with Visual Studio Code
66 
67Add 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)`.
68 
69More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
70 
71<table>
72<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
73<tr valign=top>
74<td>
75 
76```json
77{
78  "mcp": {
79    "servers": {
80      "terraform": {
81        "command": "docker",
82        "args": [
83          "run",
84          "-i",
85          "--rm",
86          "-e", "TFE_TOKEN=${input:tfe_token}",
87          "-e", "TFE_ADDRESS=${input:tfe_address}",
88          "hashicorp/terraform-mcp-server:0.4.0"
89        ]
90      }
91    },
92    "inputs": [
93      {
94        "type": "promptString",
95        "id": "tfe_token",
96        "description": "Terraform API Token",
97        "password": true
98      },
99      {
100        "type": "promptString",
101        "id": "tfe_address",
102        "description": "Terraform Address",
103        "password": false
104      }
105    ]
106  }
107}
108```
109</td>
110<td>
111 
112```json
113{
114  "mcp": {
115    "servers": {
116      "terraform": {
117        "command": "docker",
118        "args": [
119          "run",
120          "-i",
121          "--rm",
122          "hashicorp/terraform-mcp-server:0.2.3"
123        ]
124      }
125    }
126  }
127}
128```
129 
130</td>
131</tr>
132</table>
133 
134Optionally, 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.
135 
136<table>
137<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
138<tr valign=top>
139<td>
140 
141```json
142{
143  "servers": {
144    "terraform": {
145      "command": "docker",
146      "args": [
147        "run",
148        "-i",
149        "--rm",
150        "-e", "TFE_TOKEN=${input:tfe_token}",
151        "-e", "TFE_ADDRESS=${input:tfe_address}",
152        "hashicorp/terraform-mcp-server:0.4.0"
153      ]
154    }
155  },
156  "inputs": [
157    {
158      "type": "promptString",
159      "id": "tfe_token",
160      "description": "Terraform API Token",
161      "password": true
162    },
163    {
164      "type": "promptString",
165      "id": "tfe_address",
166      "description": "Terraform Address",
167      "password": false
168    }
169  ]
170}
171```
172 
173</td>
174<td>
175 
176```json
177{
178  "servers": {
179    "terraform": {
180      "command": "docker",
181      "args": [
182        "run",
183        "-i",
184        "--rm",
185        "hashicorp/terraform-mcp-server:0.2.3"
186      ]
187    }
188  }
189}
190```
191</td>
192</tr>
193</table>
194 
195 
196[<img alt="Install in VS Code (docker)" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Terraform%20MCP&color=0098FF">](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22terraform%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22hashicorp%2Fterraform-mcp-server%22%5D%7D)
197[<img alt="Install in VS Code Insiders (docker)" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Terraform%20MCP&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22terraform%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22hashicorp%2Fterraform-mcp-server%22%5D%7D)
198 
199### Usage with Cursor
200 
201Add this to your Cursor config (`~/.cursor/mcp.json`) or via Settings → Cursor Settings → MCP:
202 
203<table>
204<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
205<tr valign=top>
206<td>
207 
208```json
209{
210  "mcpServers": {
211    "terraform": {
212      "command": "docker",
213      "args": [
214        "run",
215        "-i",
216        "--rm",
217        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
218        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
219        "hashicorp/terraform-mcp-server:0.4.0"
220      ]
221    }
222  }
223}
224```
225 
226</td>
227<td>
228 
229```json
230{
231  "servers": {
232    "terraform": {
233      "command": "docker",
234      "args": [
235        "run",
236        "-i",
237        "--rm",
238        "hashicorp/terraform-mcp-server:0.2.3"
239      ]
240    }
241  }
242}
243```
244</td>
245</tr>
246</table>
247 
248<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=terraform&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCJoYXNoaWNvcnAvdGVycmFmb3JtLW1jcC1zZXJ2ZXIiXX0%3D">
249  <img alt="Add terraform MCP server to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" height="32" />
250</a>
251 
252### Usage with Claude Desktop / Amazon Q Developer / Amazon Q CLI
253 
254More about using MCP server tools in Claude Desktop [user documentation](https://modelcontextprotocol.io/quickstart/user). Read more about using MCP server in Amazon Q from the [documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html).
255 
256<table>
257<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
258<tr valign=top>
259<td>
260 
261```json
262{
263  "mcpServers": {
264    "terraform": {
265      "command": "docker",
266      "args": [
267        "run",
268        "-i",
269        "--rm",
270        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
271        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
272        "hashicorp/terraform-mcp-server:0.4.0"
273      ]
274    }
275  }
276}
277```
278 
279</td>
280<td>
281 
282```json
283{
284  "mcpServers": {
285    "terraform": {
286      "command": "docker",
287      "args": [
288        "run",
289        "-i",
290        "--rm",
291        "hashicorp/terraform-mcp-server:0.2.3"
292      ]
293    }
294  }
295}
296```
297</td>
298</tr>
299</table>
300 
301### Usage with Claude Code
302 
303More about using and adding MCP server tools in Claude Code [user documentation](https://docs.claude.com/en/docs/claude-code/mcp)
304 
305- Local (`stdio`) Transport
306 
307```sh
308claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
309```
310 
311- Remote (`streamable-http`) Transport
312 
313```sh
314# Run server (example)
315docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server
316 
317# Add to Claude Code
318claude mcp add --transport http terraform http://localhost:8080/mcp
319```
320 
321### Usage with Gemini extensions
322 
323For 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
324 
325```
326# ~/.gemini/.env
327TFE_ADDRESS=your_tfe_address_here
328TFE_TOKEN=your_tfe_token_here
329```
330 
331Install the extension & run Gemini
332 
333```
334gemini extensions install https://github.com/hashicorp/terraform-mcp-server
335gemini
336```
337 
338## Install from source
339 
340Use the latest release version:
341 
342```console
343go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
344```
345 
346Use the main branch:
347 
348```console
349go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
350```
351 
352<table>
353<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
354<tr valign=top>
355<td>
356 
357```json
358{
359  "mcp": {
360    "servers": {
361      "terraform": {
362        "type": "stdio",
363        "command": "/path/to/terraform-mcp-server",
364        "env": {
365          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"
366        },
367      }
368    }
369  }
370}
371```
372 
373</td>
374<td>
375 
376```json
377{
378  "mcp": {
379    "servers": {
380      "terraform": {
381        "type": "stdio",
382        "command": "/path/to/terraform-mcp-server"
383      }
384    }
385  }
386}
387```
388</td>
389</tr>
390</table>
391 
392## Building the Docker Image locally
393 
394Before using the server, you need to build the Docker image locally:
395 
3961. Clone the repository:
397```bash
398git clone https://github.com/hashicorp/terraform-mcp-server.git
399cd terraform-mcp-server
400```
401 
4022. Build the Docker image:
403```bash
404make docker-build
405```
406 
4073. This will create a local Docker image that you can use in the following configuration.
408 
409```bash
410# Run in stdio mode
411docker run -i --rm terraform-mcp-server:dev
412 
413# Run in streamable-http mode
414docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev
415 
416# Filter tools (optional)
417docker run -i --rm terraform-mcp-server:dev --toolsets=registry,terraform
418docker run -i --rm terraform-mcp-server:dev --tools=search_providers,get_provider_details
419```
420 
421> **Note:** When running in Docker, you should set `TRANSPORT_HOST=0.0.0.0` to allow connections from outside the container.
422 
4234. (Optional) Test connection in http mode
424 
425```bash
426# Test the connection
427curl http://localhost:8080/health
428```
429 
4305. You can use it on your AI assistant as follow:
431 
432```json
433{
434  "mcpServers": {
435    "terraform": {
436      "command": "docker",
437      "args": [
438        "run",
439        "-i",
440        "--rm",
441        "terraform-mcp-server:dev"
442      ]
443    }
444  }
445}
446```
447 
448## Available Tools
449 
450[Check out available tools here :link:](https://developer.hashicorp.com/terraform/docs/tools/mcp-server/reference#available-tools)
451 
452## Available Resources
453 
454[Check out available resources here :link:](https://developer.hashicorp.com/terraform/docs/tools/mcp-server/reference#available-tools)
455 
456### Tool Filtering
457 
458Control which tools are available using `--toolsets` (groups) or `--tools` (individual):
459 
460```bash
461# Enable tool groups (default: registry)
462terraform-mcp-server --toolsets=registry,terraform
463 
464# Enable specific tools only
465terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces
466```
467 
468Available toolsets: `registry`, `registry-private`, `terraform`, `all`, `default`. See `pkg/toolsets/mapping.go` for individual tool names. Cannot use both flags together.
469 
470## Transport Support
471 
472The Terraform MCP Server supports multiple transport protocols:
473 
474### 1. Stdio Transport (Default)
475Standard input/output communication using JSON-RPC messages. Ideal for local development and direct integration with MCP clients.
476 
477### 2. StreamableHTTP Transport
478Modern HTTP-based transport supporting both direct HTTP requests and Server-Sent Events (SSE) streams. This is the recommended transport for remote/distributed setups.
479 
480**Features:**
481- **Endpoint**: `http://{hostname}:8080/mcp`
482- **Health Check**: `http://{hostname}:8080/health`
483- **Environment Configuration**: Set `TRANSPORT_MODE=http` or `TRANSPORT_PORT=8080` to enable
484 
485## Session Modes
486 
487The Terraform MCP Server supports two session modes when using the StreamableHTTP transport:
488 
489- **Stateful Mode (Default)**: Maintains session state between requests, enabling context-aware operations.
490- **Stateless Mode**: Each request is processed independently without maintaining session state, which can be useful for high-availability deployments or when using load balancers.
491 
492To enable stateless mode, set the environment variable:
493```bash
494export MCP_SESSION_MODE=stateless
495```
496 
497## Development
498 
499### Prerequisites
500- Go (check [go.mod](./go.mod) file for specific version)
501- Docker (optional, for container builds)
502 
503### Available Make Commands
504 
505| Command | Description |
506|---------|-------------|
507| `make build` | Build the binary |
508| `make test` | Run all tests |
509| `make test-e2e` | Run end-to-end tests |
510| `make docker-build` | Build Docker image |
511| `make run-http` | Run HTTP server locally |
512| `make docker-run-http` | Run HTTP server in Docker |
513| `make test-http` | Test HTTP health endpoint |
514| `make clean` | Remove build artifacts |
515| `make help` | Show all available commands |
516 
517## Contributing
518 
5191. Fork the repository
5202. Create your feature branch
5213. Make your changes
5224. Run tests
5235. Submit a pull request
524 
525## License
526 
527This project is licensed under the terms of the MPL-2.0 open source license. Please refer to [LICENSE](./LICENSE) file for the full terms.
528 
529## Security
530 
531For security issues, please contact security@hashicorp.com or follow our [security policy](https://www.hashicorp.com/en/trust/security/vulnerability-management).
532 
533## Support
534 
535For bug reports and feature requests, please open an issue on GitHub.
536 
537For general questions and discussions, open a GitHub Discussion.
538