Stdio mode

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

StreamableHTTP mode

terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--toolsets ] [--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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

<table>
<tr><th>Version 0.3.0+ or greater</th><th>Version 0.2.3 or lower</th></tr>
<tr valign=top>
<td>

```json
{
  "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:0.4.0"
        ]
      }
    },
    "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": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "hashicorp/terraform-mcp-server:0.2.3"
        ]
      }
    }
  }
}

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.

Version 0.3.0+ or greater Version 0.2.3 or lower

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

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

Usage with Cursor

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

Version 0.3.0+ or greater Version 0.2.3 or lower

{
  "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:0.4.0"
      ]
    }
  }
}

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

Usage with Claude Desktop / Amazon Q Developer / Amazon Q CLI

More about using MCP server tools in Claude Desktop user documentation. Read more about using MCP server in Amazon Q from the documentation.

Version 0.3.0+ or greater Version 0.2.3 or lower

{
  "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:0.4.0"
      ]
    }
  }
}

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

Usage with Claude Code

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

Local (stdio) Transport

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

Remote (streamable-http) Transport

# Run server (example)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp

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/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

Install the extension & run Gemini

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

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

Version 0.3.0+ or greater Version 0.2.3 or lower

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

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

Building the Docker Image locally

Before using the server, you need to build the Docker image locally:

Clone the repository:

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

Build the Docker image:

make docker-build

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

# Run in stdio mode
docker run -i --rm terraform-mcp-server:dev

# Run in streamable-http mode
docker 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,terraform
docker run -i --rm terraform-mcp-server:dev --tools=search_providers,get_provider_details

Note: When running in Docker, you should set TRANSPORT_HOST=0.0.0.0 to allow connections from outside the container.

(Optional) Test connection in http mode

# Test the connection
curl http://localhost:8080/health

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:

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_providers,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

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

Development

Prerequisites

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

Available Make Commands

Command	Description
`make build`	Build the binary
`make test`	Run all tests
`make test-e2e`	Run end-to-end tests
`make docker-build`	Build Docker image
`make run-http`	Run HTTP server locally
`make docker-run-http`	Run HTTP server in Docker
`make test-http`	Test HTTP health endpoint
`make clean`	Remove build artifacts
`make help`	Show all available commands

Contributing

Fork the repository
Create your feature branch
Make your changes
Run tests
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 security@hashicorp.com 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.