HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Deploy Terraform MCP server locally

This topic describes how to deploy the Terraform Model Context Protocol (MCP) server in your local environment and connect it to your AI agent. Local deployments are best for getting started, working on a solo project, and developing server customizations.

For information about deploying the server to a remote environment, refer to Deploy Terraform MCP server to a remote environment.

Overview

Complete the following steps to deploy the MCP server locally:

  1. Choose the environment for your local deployment. You can use the following installation methods in remote and local environments, but we recommend deploying with Docker when getting started:

    • Docker: If you are getting started or aren't working on a collaborative project, we recommend running the server in a local Docker container.
    • Pre-compiled binary: We recommend downloading and installing the pre-compiled binary if you have special OS requirements.
    • From source: If you are developing customizations for the MCP server, we recommend running it from the source code.

  2. If you intend to connect the server to your HCP Terraform or Terraform Enterprise organization, create an API token for authentication.

  3. Configure the server. Set the transport mode and configure any other settings that match your requirements. To connect to HCP Terraform or Terraform Enterprise, you must also configure the server to present your API token.

Requirements

The requirements depend on how you configure your installation environment.

Containerization software

To use the Terraform MCP server Docker image, you must have Docker Engine v20.10.21+ or Docker Desktop v4.14.0+ on your local machine. Refer to the Docker documentation for installation instructions.

You can run the server on other containerization platforms, such as Podman or Colima, but we have not tested them and don’t provide support.

Pre-compiled binary

You can run the compiled binary on the following operating systems and architectures:

  • MacOS: amd64, arm64
  • FreeBSD: 386, amd64
  • Linux: 386, amd64, arm, arm64
  • Solaris: amd64
  • Windows: 386, amd64

Source

You must install the Go development environment.

HCP Terraform and Terraform Enterprise

If connecting to HCP Terraform or Terraform Enterprise, you must have network access to https://app.terraform.io or your Terraform Enterprise endpoint.

You must also present an API token. Refer to API Tokens in the HCP Terraform documentation or API Tokens in the Terraform Enterprise documentation for instructions on creating API tokens.

Follow security best practices any time you generate a token for accessing HCP Terraform or Terraform Enterprise. Refer to Secure configuration for additional information.

Docker

Docker provides the most reliable and consistent way to run the Terraform MCP server across different environments. To run the server in Docker, start Docker on your system, then integrate with your AI assistant.

Connect to HCP Terraform or Terraform Enterprise

To allow the server to connect to your private registry on HCP Terraform or Terraform Enterprise, set the TFE_TOKEN environment variable to your HCP Terraform or Terraform Enterprise API token. To connect the server to Terraform Enterprise, you must also set the TFE_HOSTNAME environment variable to the URL of your Terraform Enterprise deployment. Then, add the configurations to the server arguments. Refer to the environment variables reference for more information.

  1. Verify Visual Studio Code is installed.

  2. Verify the GitHub Copilot extension is installed and chats are configured to Agent mode.

  3. Verify MCP support is enabled in VS Code. Refer to the VS Code MCP documentation for more information.

  4. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

    {
  "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"
        ]
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "tfe_token",
        "description": "Terraform API Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "tfe_address",
        "description": "Terraform Address",
        "password": false
      }
    ]
  }
}

    Alternatively, to use the server in a specific workspace, create an mcp.json file with the following configuration in your workspace's .vscode directory:

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

Connect to the public registry only

The server does not require a token to retrieve information in the public Terraform registry.

  1. Verify Visual Studio Code is installed.

  2. Verify the GitHub Copilot extension is installed and chats are configured to Agent mode.

  3. Verify MCP support is enabled in VS Code. Refer to the VS Code MCP documentation for more information.

  4. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

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

    Alternatively, to use the server in a specific workspace, create an mcp.json file with the following configuration in your workspace's .vscode directory:

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

  5. Verify the integration by opening the chat interface and selecting Agent from the mode settings.

  6. Click the tools icon to verify that Terraform MCP server tools appear in the available tools list.

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

Download the binary for your operating system and architecture from the release library. Then, add the configure your client settings.

If you downloaded a supported version of the binary, you can enable authentication in the configuration. Otherwise, you can run the server without authentication.

Enable authentication

Set the TFE_TOKEN environment variable to your HCP Terraform or Terraform Enteprise API token. Set the TFE_HOSTNAME environment variable to the URL of your Terraform Enteprise deployment. Refer to the environment variables reference for more information.

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

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

Run without authentication

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

Install from source

Installing from source gives you access to the latest features and allows for customization. This method requires a Go development environment.

  1. Install the latest stable release.

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

    Alternatively, you can install the development version on main.

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

  2. After installation, add the following configuration to your client.

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

    Replace /path/to/terraform-mcp-server with the actual path to your downloaded binary. The binary location depends on your Go installation and GOPATH configuration.

Use which terraform-mcp-server to find the installed binary path.

Start the server

If you installed the pre-compiled binary or built the binary from source, you must start the server manually. You can use the terraform-mcp-server CLI and specify the transport protocol you want to use to start the server. Refer to the transport protocols reference for more information.

Start the server in stdio mode. 

$ terraform-mcp-server stdio [--log-file /path/to/log]

Run the following command on the local instance to start the server in streamable-http mode:

$ terraform-mcp-server streamable-http \
  [--transport-port 8080] \
  [--transport-host 127.0.0.1] \
  [--mcp-endpoint /mcp] \
  [--log-file /path/to/log]

Instead of setting values manually, you can also use the supported environment variables. Refer to the environment variables reference for details.

Next steps

  • Begin prompting your AI model about Terraform configurations. Refer to Prompt an AI model for guidance on effective prompting techniques.
  • The server provides access to up-to-date provider documentation.
  • Ask for help with specific Terraform resources and modules.
  • Explore advanced configuration options for your specific deployment needs.
Edit this page on GitHub