Terraform MCP 服务器

Terraform MCP 服务器是一个 模型上下文协议 (MCP) 服务器，它与 Terraform Registry API 进行无缝集成，为基础设施即代码 (IaC) 开发提供了先进的自动化和交互功能。

特性

• 双传输支持：同时支持 Stdio 和 StreamableHTTP 传输，并可配置端点
• Terraform 注册表集成：直接集成公共 Terraform 注册表 API，用于提供程序、模块和策略
• HCP Terraform 和 Terraform Enterprise 支持：全面的工作区管理、组织/项目列表以及私有注册表访问
• 工作区操作：创建、更新、删除工作区，支持变量、标签和运行管理
• OTel 指标用于监控工具使用情况：与 OpenTelemetry 计量器集成，以跟踪 Streamable HTTP 模式下的工具调用量、延迟和失败情况

安全提示： 目前阶段，MCP 服务器仅适用于本地使用。如果使用 StreamableHTTP 传输，请务必配置 MCP_ALLOWED_ORIGINS 环境变量，以限制仅允许受信任的来源访问。这有助于防止 DNS 重绑定攻击和其他跨域漏洞。

安全提示： 根据查询内容，MCP 服务器可能会将某些 Terraform 数据暴露给 MCP 客户端和 LLM。请勿将 MCP 服务器与不受信任的 MCP 客户端或 LLM 一起使用。

法律提示： 您对第三方 MCP 客户端/LLM 的使用完全受该等 MCP/LLM 使用条款的约束，IBM 对此类第三方工具的性能不承担任何责任。IBM 明确声明不对第三方 MCP 客户端/LLM 承担任何保证或责任，并且可能无法为您提供因第三方工具引起的问题的支持服务。

注意事项： MCP 服务器提供的输出和建议是动态生成的，可能会根据查询、模型以及连接的 MCP 客户端而有所不同。用户应在实施之前仔细审查所有输出/建议，以确保其符合贵组织的安全最佳实践、成本效益目标和合规要求。

先决条件

1. 确保已安装并运行 Docker，以便在容器化环境中使用该服务器。
2. 安装一个支持模型上下文协议 (MCP) 的 AI 助手。

命令行选项

环境变量：

# Stdio 模式
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP 模式
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

指令

MCP 服务器的默认指令位于 cmd/terraform-mcp-server/instructions.md 中。如果这些指令不适合贵组织的 Terraform 实践，或者 MCP 服务器产生了不准确的响应，请将其替换为您自己的指令，并重新构建容器或二进制文件。此类指令的示例位于 instructions/example-mcp-instructions.md。

AGENTS.md 实质上充当编码代理的 README 文件：一个专门且可预测的地方，用于提供上下文和指令，以帮助 AI 编码代理完成您的项目。一个 AGENTS.md 文件可以与不同的编码代理配合使用。此类指令的示例位于 instructions/example-AGENTS.md 中，要使用它，只需将名为 AGENTS.md 的文件提交到您存放 Terraform 配置的目录中。

安装

在 Visual Studio Code 中的使用

将以下 JSON 块添加到 VS Code 的用户设置（JSON）文件中。您可以通过按 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 来完成此操作。

有关在 VS Code 的代理模式下使用 MCP 服务器工具的更多信息，请参阅 代理模式文档。

{
  "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.5.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"
        ]
      }
    }
  }
}

可选地，您可以将类似的示例（即不包含 mcp 键）添加到工作区中的 .vscode/mcp.json 文件中。这将允许您与他人共享配置。

{
  "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.5.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"
      ]
    }
  }
}

在 Cursor 中的使用

将以下内容添加到您的 Cursor 配置文件 (~/.cursor/mcp.json) 中，或通过“设置”→“Cursor 设置”→“MCP”进行配置：

{
  "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.5.0"
      ]
    }
  }
}

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

在 Claude Desktop / Amazon Q Developer / Amazon Q CLI 中的使用

有关在 Claude Desktop 中使用 MCP 服务器工具的更多信息，请参阅 用户文档。有关在 Amazon Q 中使用 MCP 服务器的更多信息，请参阅 文档。

{
  "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.5.0"
      ]
    }
  }
}

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

在 Claude Code 中的使用

有关在 Claude Code 中使用和添加 MCP 服务器工具的更多信息，请参阅 用户文档。

• 本地（stdio）传输

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

• 远程（streamable-http）传输

# 启动服务器（示例）
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# 添加到 Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp

在 Gemini 扩展中的使用

为确保安全，请勿硬编码您的凭据，而是创建或更新 ~/.gemini/.env 文件（其中 ~ 是您的主目录或项目目录），用于存储 HCP Terraform 或 Terraform Enterprise 的凭据。

# ~/.gemini/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

安装扩展并运行 Gemini：

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

与 Bob IDE / Shell 的使用

关于在 Bob IDE 或 Shell 中使用和添加 MCP 服务器工具的更多信息，请参阅 在 Bob 中使用 MCP。

{
  "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.5.0"
      ],
      "disabled": false
    }
  }
}

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

从源代码安装

使用最新发布版本：

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

使用主分支：

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

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

在本地构建 Docker 镜像

在使用服务器之前，您需要在本地构建 Docker 镜像：

1. 克隆仓库：

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

2. 构建 Docker 镜像：

make docker-build

3. 这将创建一个本地 Docker 镜像，您可以在以下配置中使用。

# 以 stdio 模式运行
docker run -i --rm terraform-mcp-server:dev

# 以可流式传输的 HTTP 模式运行
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# 筛选工具（可选）
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

注意： 在 Docker 中运行时，应设置 TRANSPORT_HOST=0.0.0.0 以允许来自容器外部的连接。

4. （可选）测试 HTTP 模式下的连接

# 测试连接
curl http://localhost:8080/health

5. 您可以将其用于您的 AI 助手，如下所示：

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

可用工具

在此处查看可用工具 :link:

可用资源

在此处查看可用资源 :link:

工具筛选

使用 --toolsets（组）或 --tools（单个工具）来控制哪些工具可用：

# 启用工具组（默认：registry）
terraform-mcp-server --toolsets=registry,terraform

# 仅启用特定工具
terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces

可用工具集：registry、registry-private、terraform、all、default。有关单个工具名称，请参阅 pkg/toolsets/mapping.go 文件。不能同时使用这两个标志。

传输支持

Terraform MCP 服务器支持多种传输协议：

1. Stdio 传输（默认）

使用 JSON-RPC 消息进行标准输入/输出通信。非常适合本地开发和直接与 MCP 客户端集成。

2. 可流式传输的 HTTP 传输

现代基于 HTTP 的传输，支持直接 HTTP 请求和服务器发送事件 (SSE) 流。这是推荐用于远程/分布式部署的传输方式。

功能：

• 端点：http://{hostname}:8080/mcp
• 健康检查：http://{hostname}:8080/health
• 环境配置：设置 TRANSPORT_MODE=http 或 TRANSPORT_PORT=8080 以启用

会话模式

Terraform MCP 服务器在使用可流式传输的 HTTP 传输时支持两种会话模式：

• 有状态模式（默认）：在请求之间保持会话状态，从而实现上下文感知的操作。
• 无状态模式：每个请求独立处理，不保持会话状态，这在高可用性部署或使用负载均衡器时非常有用。

要启用无状态模式，请设置环境变量：

export MCP_SESSION_MODE=stateless

故障排除

企业代理 / TLS 检查（Zscaler 等）

如果您位于执行 TLS 检查的企业代理之后（如 Zscaler Internet Access），可能会看到证书错误：

tls: failed to verify certificate: x509: certificate signed by unknown authority

解决方案：将您的企业 CA 证书挂载到容器中：

docker run -i --rm \
  -v /path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem \
  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
  hashicorp/terraform-mcp-server:0.5.0

对于 MCP 客户端配置：

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem",
        "-e", "SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem",
        "-e", "TFE_TOKEN=<>",
        "hashicorp/terraform-mcp-server:0.5.0"
      ]
    }
  }
}

替代方案：直接运行二进制文件

如果您的环境中不允许使用 Docker，您可以直接安装并运行服务器二进制文件，它将使用您系统的证书存储：

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

开发

先决条件

• Go（请参阅 go.mod 文件以获取具体版本）
• Docker（可选，用于容器构建）

可用的 Make 命令

贡献

1. 分支仓库
2. 创建您的功能分支
3. 进行更改
4. 运行测试
5. 提交拉取请求

许可证

本项目依据 MPL-2.0 开源许可证条款授权。完整条款请参阅 LICENSE 文件。

安全

如遇安全问题，请联系 security@hashicorp.com，或遵循我们的 安全政策。

支持

如需提交 bug 报告或功能请求，请在 GitHub 上创建 issue。

如需进行一般性问题讨论，请在 GitHub Discussions 中发帖。

Terraform MCP Server 快速上手指南

Terraform MCP Server 是一个基于模型上下文协议（MCP）的服务端工具，旨在让 AI 助手无缝集成 Terraform Registry API、HCP Terraform 及 Terraform Enterprise。它支持自动化基础设施即代码（IaC）开发，包括工作区管理、模块查询及策略执行。

环境准备

在开始之前，请确保满足以下前置条件：

1. Docker 环境：必须安装并运行 Docker，因为官方推荐通过容器化方式部署该服务。
   • 下载地址：https://www.docker.com/
2. 支持 MCP 的 AI 助手：安装已集成 Model Context Protocol (MCP) 的 AI 编程助手（如 VS Code + Copilot、Cursor、Claude Desktop 等）。
3. Terraform 凭证（可选但推荐）：若需连接 HCP Terraform 或 Terraform Enterprise，请准备好 TFE_TOKEN 和 TFE_ADDRESS。

安装步骤

根据你使用的 AI 助手不同，配置方式略有差异。以下提供主流工具的配置文件片段。

1. Visual Studio Code (VS Code)

打开 VS Code 命令面板 (Ctrl + Shift + P)，选择 Preferences: Open User Settings (JSON)，添加以下配置。

适用于 v0.3.0+ 版本（推荐）：

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

保存后，VS Code 会在首次使用时提示你输入 Token 和地址。

2. Cursor

编辑 Cursor 配置文件 ~/.cursor/mcp.json（或在设置界面中找到 MCP 配置），填入以下内容：

{
  "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.5.0"
      ]
    }
  }
}

请将 <<PASTE_TFE_ADDRESS_HERE>> 和 <<PASTE_TFE_TOKEN_HERE>> 替换为你实际的 Terraform 地址和 Token。

3. Claude Desktop / Amazon Q Developer

找到对应的 MCP 配置文件（通常位于 claude_desktop_config.json 或类似路径），添加：

{
  "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.5.0"
      ]
    }
  }
}

4. Claude Code (命令行模式)

如果你使用 Claude Code CLI，可以直接通过命令添加：

本地 Stdio 模式：

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

远程 HTTP 模式： 先启动服务器：

docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

然后在 Claude Code 中配置连接该端口。

基本使用

配置完成后，重启你的 AI 助手即可生效。你可以在对话中直接使用自然语言指令与 Terraform 交互。

使用示例：

1. 查询模块：

   "帮我查找 Terraform Registry 上最新的 AWS VPC 模块，并列出其主要输入变量。"

2. 管理工作区（需配置 TFE Token）：

   "列出我组织 'my-org' 下的所有 Terraform 工作区。" "为项目 'web-app' 创建一个新的工作区，并设置环境变量 'AWS_REGION' 为 'us-east-1'。"

3. 生成代码：

   "根据最佳实践，为我生成一个包含 S3 存储桶和 CloudFront 分发的 Terraform 配置代码。"

安全提示：

• 该服务默认仅限本地使用。若启用 streamable-http 模式，务必设置 MCP_ALLOWED_ORIGINS 环境变量以限制访问来源，防止跨站攻击。
• 请勿将包含敏感数据的 Terraform 状态暴露给不受信任的 MCP 客户端或 LLM。
• AI 生成的代码和建议仅供参考，实施前请务必进行人工审查，确保符合安全规范和成本要求。