Skip to content

Updating documentation for Terraform MCP Server #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+265 −127
Open

Updating documentation for Terraform MCP Server #693

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6fbfba0
updating documentation for Terraform MCP Server
gautambaghel Aug 6, 2025
19dab49
further docs improvements
gautambaghel Aug 6, 2025
b388217
adding resources to the documentation
gautambaghel Aug 6, 2025
627727a
fixing issues raised in the PR review
gautambaghel Aug 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
294 changes: 189 additions & 105 deletions content/terraform-docs-common/docs/docs/tools/mcp-server/deploy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,69 +6,93 @@ description: |-

# Deploy the Terraform MCP server

The Terraform MCP (Model Context Protocol) server runs in a Docker container that you can deploy to either your local workstation or a remote instance. When running the server locally, start it in the default `stdio` mode. In this mode, the server communicates over standard input/output. When running the server on a remote instance, start the server in `streamable-http` mode so that you can communicate with the server using the Streamable HTTP transport.
The Terraform Model Context Protocol (MCP) server enables AI models to generate Terraform configuration using up-to-date information from the Terraform registry. This page explains how to install, configure, and integrate the server with your AI client.

@include 'beta.mdx'

## Overview

Complete the following steps to deploy the server.
The Terraform MCP server is a specialized service that provides AI models with access to current Terraform provider documentation and module information. You can deploy the server in to the following environments:

### Standard IO transport
- **Local deployment**: Run the server on your workstation using `stdio` mode for direct communication through standard input/output
- **Remote deployment**: Run the server on a remote instance using `streamable-http` mode for network-based communication

1. Enable MCP in your client
1. Install the server
1. Configure your client
### Installation methods

### Streamable HTTP transport
Choose from three installation options based on your environment and preferences:

1. Configure environment variables
1. Build the Docker image
1. Configure your client
1. Start the server
| Method | Best for | Requirements |
|--------|----------|--------------|
| [Docker](#run-in-docker) | Most users, consistent environments | Docker Engine v20.10.21+ or Docker Desktop v4.14.0+. Refer to the [Docker documentation](https://docs.docker.com/desktop) for installation instructions. |
| [Compiled binary](#run-the-compiled-binary) | Lightweight deployments, specific OS needs | Compatible operating system |
| [Source installation](#install-from-source) | Development, customization | Go development environment |

## Requirements
## Run in Docker

Docker provides the most reliable and consistent way to run the Terraform MCP server across different environments.

One of the following Docker distributions is required:
1. Start Docker on your system.

- Docker Engine v20.10.21+
- Docker Desktop v4.14.0+
1. Integrate with your AI client:

Refer to the [Docker documentation](https://docs.docker.com/desktop) for installation instructions.

The following MCP clients are supported:

- VS Code with CoPilot. Refer to the [VS Code documentation](https://code.visualstudio.com/docs) for installation instructions.
- Cursor. Refer to the [Cursor website](https://www.cursor.com) for more information.
- Anthropic Claude Desktop. Refer to the [Anthropic Claude Desktop documentation](https://support.anthropic.com/en/articles/10065433-installing-claude-for-desktop) for installation instructions.
<Tabs>

## Enable MCP in your client
<Tab heading="Visual Studio Code">

Refer to your client's documentation for instructions on enabling MCP:
1. Verify [Visual Studio Code](https://code.visualstudio.com/docs) is installed.
1. Verify the [GitHub Copilot extension](https://code.visualstudio.com/docs/copilot/overview) is installed and chats are configured to `Agent` mode.
1. Verify MCP support enabled, refer to the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more information.

- [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
- [Cursor](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)
- [Anthropic Claude Desktop](https://modelcontextprotocol.io/quickstart/user)
1. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

## Install the server
```json
{
"mcp": {
"servers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server"
]
}
}
}
}
```

You can install the server using the following methods if you intend to run the server locally:
1. (_Optional_) To use the server in a specific workspace, create an `mcp.json` file with the following configuration in your workspace's `.vscode` directory:

- Install the binary into your client. The binaries are available at [releases.hashicorp.com](https://releases.hashicorp.com/terraform-mcp-server/).
- Install from source into your client.
```json
{
"servers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server"
]
}
}
}
```

For remote installations, download the source to the remote and build the Docker image.
1. To verify the integration, open the chat interface and select **Agent** from the mode settings.
1. Click the tools icon to verify that Terraform MCP server tools appear in the available tools list.

### Compiled binary
</Tab>

Refer to [Requirements](#requirements) for supported clients.

<Tabs>
<Tab heading="Cursor">

<Tab heading="VS Code">
1. Verify [Cursor](https://www.cursor.com) is installed.
1. Verify the MCP support configured, refer to [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) for more information.

To install the server so that it's available for all workspaces, add the following JSON block to your user setting JSON file:
1. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

```json
{
Expand All @@ -88,7 +112,7 @@ To install the server so that it's available for all workspaces, add the followi
}
```

Alternatively, you can install the server in specific workspaces. Create an `mcp.json` file in the `.vscode` directory of your workspace and add the following JSON block:
1. (_Optional_) To use the server in a specific workspace, create an `mcp.json` file with the following configuration in your workspace's `.vscode` directory:

```json
{
Expand All @@ -106,55 +130,115 @@ Alternatively, you can install the server in specific workspaces. Create an `mcp
}
```

1. To verify the installation, open the chat pane and select **Chat Settings** from the ellipses menu.
1. Choose **Agent** from the **Default new chat mode** drop-down menu.
1. Select **MCP** from the **Cursor Settings** sidebar to verify that Terraform MCP server tools are enabled.

</Tab>

<Tab heading="Claude Desktop, Amazon Q Developer and CLI">
<Tab heading="Claude Desktop">

1. Verify [Claude Desktop](https://support.anthropic.com/en/articles/10065433-installing-claude-for-desktop) is installed.
1. Verify MCP support is configured, refer to [Claude Desktop's MCP documentation](https://modelcontextprotocol.io/quickstart/user) for more information.

**Configuration:**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Configuration:**


Create an `mcp.json` file and add the following configuration:
Create or edit the `mcp.json` file with the following configuration:

```json
{
"mcpServers": {
"servers": {
"hcp-terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server:<version>"
]
}
}
}
"mcpServers": {
"servers": {
"hcp-terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server:<version>"
]
}
}
}
}
```

1. To verify the integration, open the chat pane and click the **search and tools** slider icon.
1. Click **terraform-mcp-server** to verify that all tools are enabled and accessible.

</Tab>

<Tab heading="Amazon Q">

1. Verify [Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html) is installed.
1. Verify MCP support is configured, refer to [Amazon Q's MCP documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) for more information.

1. Create or edit the `mcp.json` file with the following configuration:

```json
{
"mcpServers": {
"servers": {
"hcp-terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server:<version>"
]
}
}
}
}
```

</Tab>

</Tabs>

Start or restart Docker to start the container using the standard transport.
## Run the compiled binary

The compiled binary option provides a lightweight installation without Docker dependencies. This method is ideal when you want to minimize resource usage or work in environments with restricted container access.

1. Download the binary for your operating system and architecture, visit the [release library](https://releases.hashicorp.com/terraform-mcp-server).
1. Add the following configuration to your client settings:

**Client configuration:**

Add this configuration to your client settings:

```json
{
"mcp": {
"servers": {
"terraform": {
"command": "/path/to/terraform-mcp-server",
"args": ["stdio"]
}
}
}
}
```

1. Replace `/path/to/terraform-mcp-server` with the actual path to your downloaded binary.

### Install from source
## Install from source

You can pull the source from either the `latest` release version or pull from the `main` branch to install from source.
Installing from source gives you access to the latest features and allows for customization. This method requires a Go development environment.

Latest:
1. Run the following `go` command to install the latest stable release:

```shell-session
$ go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
```

Main:

1. (_Optional_) Run the following `go` command to install the development version on `main`:
```shell-session
$ go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
```

After pulling the image, add the following JSON block to your client and specify the path to the server binary in the `command` attribute:

1. After installation, add the following configuration to your client:

```json
{
Expand All @@ -169,67 +253,67 @@ After pulling the image, add the following JSON block to your client and specify
}
```

Start or restart Docker to start the container using the standard transport.

## Configure environment variables

If you intend to run the MCP server on a remote instance, log into the remote machine and specify the following environment variables:
The binary location depends on your Go installation and `GOPATH` configuration. Use `which terraform-mcp-server` to find the installed binary path.

| Variable | Description | Default |
|----------|-------------|---------|
| `TRANSPORT_MODE` | Set to `streamable-http` to enable HTTP transport | `stdio` |
| `TRANSPORT_HOST` | Host to bind the HTTP server | `0.0.0.0` |
| `TRANSPORT_PORT` | HTTP server port | `8080` |
## Configuration reference

## Build the Docker image
### Transport protocols

You can download the source to your local machine or to a remote instance and build the server locally.
| Transport | Best for | How it works | Usage |
|------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| `stdio` | Local development and direct integration with MCP clients | Uses standard input/output for JSON-RPC message communication | Automatically used when no specific transport mode is configured |
| `streamableHTTP` | Remote deployments, distributed setups, production environments | HTTP-based transport with support for both direct HTTP requests | Enable by setting `TRANSPORT_MODE=streamable-http` |

1. Clone the repository:

```bash
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
```

2. Build the Docker image:
### Environment variables

```bash
make docker-build
```
Configure the server behavior using these environment variables:

Use the image to run the server in `stdio` mode or to run it in `streamable-http` mode:
| Variable | Purpose | Default Value | Example | Options |
|----------------------|--------------------------|-----------------|--------------------------|-----------------------------------------|
| `TRANSPORT_MODE` | Communication protocol | `stdio` | `streamable-http` | `stdio`, `streamable-http` |
| `TRANSPORT_HOST` | HTTP server binding address | `127.0.0.1` | `0.0.0.0` | Any valid IP address |
| `TRANSPORT_PORT` | HTTP server port | `8080` | `3000` | Any valid port number |
| `MCP_ENDPOINT` | HTTP endpoint path | `/mcp` | `/api/mcp` | Any valid endpoint path |
| `MCP_SESSION_MODE` | Session management | `stateful` | `stateless` | `stateful`, `stateless` |
| `MCP_ALLOWED_ORIGINS`| CORS allowed origins | `""` (none) | `https://app.terraform.io`| Comma-separated list of origins or `""` |
| `MCP_CORS_MODE` | CORS policy enforcement | `strict` | `development` | `strict`, `development`, `disabled` |

`stdio` mode:
### Command line interface

```shell-session
$ docker run -i --rm terraform-mcp-server:dev
```
Control server behavior directly from the command line:

`streamable-http` mode:
<Tab>
<Tab heading="stdio">

```shell-session
$ docker run -p 8080:8080 --rm -e MODE=streamabe-http terraform-mcp-server:dev
```bash
terraform-mcp-server stdio [--log-file /path/to/log]
```

## Configure your MCP client

Complete the following steps if you are using Copilot in VS Code:
</Tab>

1. Open the chat interface and choose **Agent** from the mode settings.
1. Click the tools icon to verify that the Terraform MCP server tools are enabled.
<Tab heading="streamableHTTP">

Complete the following steps if you are using Cursor:
```bash
terraform-mcp-server streamable-http \
[--transport-port 8080] \
[--transport-host 127.0.0.1] \
[--mcp-endpoint /mcp] \
[--log-file /path/to/log]
```

1. Open the chat pane and choose **Chat Settings** from the ellipses menu.
1. Choose **Agent from the **Default new chat mode** drop-down menu.
1. Choose **MCP** from the **Cursor Settings** sidebar to verify that the Terraform MCP server tools are enabled.
</Tab>
</Tabs>

Complete the following steps if you are using Claude Desktop:
## Next steps

1. Open the chat pane and choose the **search and tools** slider icon to the bottom left of the chat pane.
1. Click **terraform-mcp-server** to verify that all the tools are enabled.
You have successfully deployed the Terraform MCP server. The server is now ready to enhance your AI model's ability to generate accurate Terraform configurations using current provider documentation and module information.

## Next steps
**Start using the server:**
- Begin prompting your AI model about Terraform configurations
- The server provides access to up-to-date provider documentation
- Ask for help with specific Terraform resources and modules

After downloading the Terraform MCP server and connecting it to your client, you can begin prompting your model about your Terraform configuration code. Refer to [Prompt an AI model](/terraform/docs/tools/mcp-server/prompt) for more information.
**Learn more:**
- Refer to [Prompt an AI model](/terraform/docs/tools/mcp-server/prompt) for guidance on effective prompting techniques
- Explore advanced configuration options for your specific deployment needs
Loading
Loading