Terraform MCP Server

What is Terraform MCP Server about?

Terraform MCP Server enables advanced automation for Terraform users by exposing Registry APIs through a Model Context Protocol (MCP) server. It allows AI assistants, IDE extensions, and other tools to query providers, modules, and policies programmatically.

How to use Terraform MCP Server?

Run locally – Install the binary with Go (go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest) or build the Docker image (make docker-build).
Choose a transport – Default is StdIO for local tools; set TRANSPORT_MODE=streamable-http (or http) for HTTP mode.
Configure the endpoint – HTTP mode listens on http://{host}:8080/mcp with health check at /health. Adjust host, port, and CORS via environment variables (TRANSPORT_HOST, TRANSPORT_PORT, MCP_ALLOWED_ORIGINS, etc.).
Integrate – Add the server definition to VS Code, Claude Desktop, Amazon Q, or any MCP‑compatible client using the Docker command shown in the README.

Key Features

Dual transport support: StdIO and Streamable‑HTTP.
Provider discovery, documentation retrieval, and version lookup.
Module search, details, and latest‑version fetching.
Sentinel policy lookup for HCP/Enterprise.
Container‑ready Docker image.
Configurable session modes (stateful vs. stateless).
Built‑in health endpoint and CORS controls.

Use Cases

IDE assistance – Real‑time lookup of provider resources or module examples while writing Terraform code.
AI chat assistants – Enable Copilot‑style agents to fetch up‑to‑date Terraform documentation on demand.
Automation pipelines – Scripts can query the latest provider version or module metadata before applying changes.
Policy compliance – Retrieve Sentinel policies and verify infrastructure against organizational rules.
Custom tooling – Build dashboards or CLI utilities that need programmatic access to the Terraform Registry.

FAQ

Q: Which transport should I use? A: StdIO is ideal for local development and direct MCP clients. Use Streamable‑HTTP for remote or distributed setups.

Q: Do I need to set CORS headers? A: In production, configure MCP_ALLOWED_ORIGINS to restrict origins and prevent DNS‑rebinding attacks.

Q: How do I switch to stateless mode? A: Set MCP_SESSION_MODE=stateless before starting the server.

Q: Can I run the server without Docker? A: Yes, install the Go binary and execute terraform-mcp-server stdio or terraform-mcp-server streamable-http.

Q: What licensing applies? A: The project is released under the MPL‑2.0 open source license.

The Terraform MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Terraform Registry APIs, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

Features

Dual Transport Support: Both Stdio and StreamableHTTP transports
Terraform Provider Discovery: Query and explore Terraform providers and their documentation
Module Search & Analysis: Search and retrieve detailed information about Terraform modules
Registry Integration: Direct integration with Terraform Registry APIs
Container Ready: Docker support for easy deployment

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

Security Note: When using the StreamableHTTP transport in production, 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.

Prerequisites

To run the server in a container, you will need to have Docker installed.
Once Docker is installed, you will need to ensure Docker is running.

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

Environment Variables:

Variable	Description	Default
`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_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`

Command Line Options

# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log]

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

Installation

Usage with VS 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.

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

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.

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

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.

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

Tool Configuration

Available Toolsets

The following sets of tools are available for the public Terraform registry:

Toolset	Tool	Description
`providers`	`search_providers`	Queries the Terraform Registry to find and list available documentation for a specific provider using the specified `service_slug`. Returns a list of provider document IDs with their titles and categories for resources, data sources, functions, or guides.
`providers`	`get_provider_details`	Fetches the complete documentation content for a specific provider resource, data source, or function using a document ID obtained from the `search_providers` tool. Returns the raw documentation in markdown format.
`providers`	`get_latest_provider_version`	Fetches the complete documentation content for a specific provider resource, data source, or function using a document ID obtained from the `search_providers` tool. Returns the raw documentation in markdown format.
`modules`	`search_modules`	Searches the Terraform Registry for modules based on specified `module_query` with pagination. Returns a list of module IDs with their names, descriptions, download counts, verification status, and publish dates
`modules`	`get_module_details`	Retrieves detailed documentation for a module using a module ID obtained from the `search_modules` tool including inputs, outputs, configuration, submodules, and examples.
`modules`	`get_latest_module_version`	Retrieves detailed documentation for a module using a module ID obtained from the `search_modules` tool including inputs, outputs, configuration, submodules, and examples.
`policies`	`search_policies`	Queries the Terraform Registry to find and list the appropriate Sentinel Policy based on the provided query `policy_query`. Returns a list of matching policies with terraform_policy_id(s) with their name, title and download counts.
`policies`	`get_policy_details`	Retrieves detailed documentation for a policy set using a terraform_policy_id obtained from the `search_policies` tool including policy readme and implementation details.

The following sets of tools are available for HCP Terraform or Terraform Enterprise:

Toolset	Tool	Description
`orgs`	`list_organizations`	Lists all Terraform organizations accessible to the authenticated user.
`projects`	`list_projects`	Lists all projects within a specified Terraform organization.

Resource Configuration

Available resources

Resource URI	Description
`/terraform/style-guide`	Terraform Style Guide - Provides access to the official Terraform style guide documentation in markdown format
`/terraform/module-development`	Terraform Module Development Guide - Comprehensive guide covering module composition, structure, providers, publishing, and refactoring best practices

Available Resource Templates

Resouce Template URI	Description
`/terraform/providers/{namespace}/name/{name}/version/{version}`	Provider Resource Template - Dynamically retrieves detailed documentation and overview for any Terraform provider by namespace, name, and version

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

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

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

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"
      ]
    }
  }
}

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.

Terraform MCP Server