hashicorp/terraform-mcp-服务器

<img src="public/images/Terraform-LogoMark_onDark.svg" width="30" align="left" style="margin-right: 12px;"/> Terraform MCP Server

Terraform MCP Server 是一个 Model Context Protocol (MCP) 服务器，它与 Terraform Registry 和 HCP Terraform API 无缝集成，为基础设施即代码 (IaC) 开发提供先进的自动化和交互能力。

Table of Contents<table width="100%">

• 双传输协议支持：支持 Stdio 和 StreamableHTTP 传输协议，且端点可配置

• Terraform Registry 集成：直接集成公共 Terraform Registry API，支持 providers、modules 和 policies

• HCP Terraform & Terraform Enterprise 支持：完整的 workspace 管理、organization/project 列表以及私有 registry 访问

• Workspace 操作：支持创建、更新、删除 workspaces，并支持 variables、tags 和 run 管理

• 用于监控工具使用情况的 OTel 指标：集成 open telemetry meters，用于在 Streamable HTTP 模式下追踪工具调用量、延迟和失败率。启用此功能时，还会公开默认的 http server 指标

> 安全注意事项： 根据查询内容，MCP server 可能会向 MCP client 和 LLM 暴露某些 Terraform 数据。请勿将 MCP server 与不可信的 MCP clients 或 LLMs 配合使用。

> 法律注意事项： 您对第三方 MCP Client/LLM 的使用仅受该 MCP/LLM 使用条款的约束，IBM 对此类第三方工具的性能不承担责任。IBM 明确否认对第三方 MCP Clients/LLMs 的任何及所有保证和责任，并且可能无法提供支持以解决由第三方工具引起的问题。> 注意： MCP server 提供的输出和建议是动态生成的，可能会根据查询、模型以及连接的 MCP client 而有所不同。用户在实施前应仔细审查所有输出/建议，以确保其符合组织的安全性最佳实践、成本效益目标和合规性要求。

Prerequisites

1. 确保已安装并运行 Docker，以便在容器化环境中使用 server。
1. 安装支持 Model Context Protocol (MCP) 的 AI assistant。

Command Line Options

Environment Variables:| Variable | Description | Default |
|----------|-------------|---------|
| TFE_ADDRESS | 设置用于 API 调用的 Terraform Enterprise/HCP Terraform 地址。必须包含协议（例如 https://app.terraform.io）。在 streamable-http 模式下，这是设置地址的唯一方式；客户端无法通过 header 或查询参数提供。 | Optional |
| TFE_TOKEN | Terraform Enterprise API token | "" (empty) |
| TF_MCP_SHARED_SECRET | 发送到 HCP Terraform / TFE 请求中 X-Tf-Mcp-Secret header 的共享密钥，用于识别源自托管 MCP 部署的请求。应仅在 TLS 上使用。 | "" (empty) |
| TFE_SKIP_TLS_VERIFY | 跳过 HCP Terraform 或 Terraform Enterprise 的 TLS 验证 | false |
| LOG_LEVEL | 日志级别：trace, debug, info, warn, error, fatal, panic（覆盖 --log-level 标志） | info |
| LOG_FORMAT | 日志格式：text 或 json（覆盖 --log-format 标志）| text |
| TRANSPORT_MODE | 设置为 streamable-http 以启用 HTTP 传输（仍支持旧版 http 值） | stdio |
| TRANSPORT_HOST | HTTP 服务器绑定的主机 | 127.0.0.1 |
| TRANSPORT_PORT | HTTP 服务器端口 | 8080 |
| MCP_ENDPOINT | HTTP 服务器端点路径 | /mcp |
| MCP_REDIRECT_ROOT_URL | 将对 / 的请求重定向到的 URL | "" |
| MCP_KEEP_ALIVE | SSE 连接的 keep-alive 间隔（例如 30s, 1m）。设置为 0 以禁用 | 0 |
| MCP_SESSION_MODE | 会话模式：stateful 或 stateless | stateful |
| MCP_ALLOWED_ORIGINS | 允许 CORS 的源列表，以逗号分隔 | "" (empty) |
| MCP_CORS_MODE | CORS 模式：strict, development, 或 disabled | strict |
| MCP_TLS_CERT_FILE | TLS 证书文件路径，非 localhost 部署必填（例如 /path/to/cert.pem） | "" (empty) |
| MCP_TLS_KEY_FILE | TLS 密钥文件路径，非 localhost 部署必填（例如 /path/to/key.pem）| "" (empty) |
| MCP_RATE_LIMIT_GLOBAL | 全局速率限制（格式：rps:burst） | 10:20 |
| MCP_RATE_LIMIT_SESSION | 单会话速率限制（格式：rps:burst） | 5:10 |
| MCP_ORGANIZATION_ALLOWLIST | 允许访问 HTTP 服务器的 HCP Terraform 组织名称 CSV 列表 | "" (empty) |
| MCP_FORWARD_CLIENT_IP | 通过 X-Forwarded-For 将客户端 IP 转发给 HCP Terraform / TFE。设置为 true 以启用 | false |
| MCP_REMOTE_IP_METHOD | 启用转发时获取客户端 IP 的方式：RemoteAddr（仅限直接连接）、X-Real-IP 或 X-Forwarded-For | RemoteAddr |
| MCP_XFF_TRUSTED_HOPS | 从 X-Forwarded-For 链右侧起计算的信任代理跳数。仅在 MCP_REMOTE_IP_METHOD=X-Forwarded-For 时使用 | 0 |
| ENABLE_TF_OPERATIONS | 启用需要显式批准的工具 | false |
| OTEL_METRICS_ENABLED | 使用 otel 启用工具和服务器指标 | false |
| OTEL_METRICS_SERVICE_VERSION | 发送指标的 terraform-mcp-server 版本，用于设置指标属性。它还有助于跟踪不同部署之间的指标 | latest |
| OTEL_METRICS_SERVICE_NAME | 标识指标的来源（例如 "terraform-mcp-server"） | terraform-mcp-server |
| OTEL_METRICS_EXPORT_INTERVAL | 控制指标刷新的频率 | 2 |
| OTEL_METRICS_ENDPOINT | OTel Collector 或后端的 URL | localhost:4318 |
| INSTANA_ENABLED | 为 streamable-http 服务器启用 Instana 仪表化（指标和 HTTP 请求追踪）。需要服务器可访问的 Instana agent。 | false |
| INSTANA_SERVICE_NAME | 如果启用了 Instana 仪表化，则为 MCP 服务器使用的服务名称 | terraform-mcp-server |

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

StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--organization-allowlist <orgs-csv>] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

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

AGENTS.md 实质上充当编码 agent 的 README：一个专门且可预测的位置，用于提供上下文和指令，以帮助 AI 编码 agent 在您的项目上工作。一个 AGENTS.md 文件可适用于不同的编码 agent。相关指令示例位于 instructions/example-AGENTS.md，若要使用它，请将名为 AGENTS.md 的文件提交到您的 Terraform 配置所在的目录。

安装

在 Visual Studio Code 中使用

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

关于在 VS Code 的 agent mode 文档 中了解更多关于使用 MCP server 工具的信息。

<table>
<tr><th>Version 0.3.0+ 或更高版本</th><th>Version 0.2.3 或更低版本</th></tr>
<tr valign=top>
<td>

{
  "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:1.2.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 的文件中。这将允许您与他人共享配置。

<table>
<tr><th>Version 0.3.0+ 或更高版本</th><th>Version 0.2.3 或更低版本</th></tr>
<tr valign=top>
<td>

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_TOKEN=${input:tfe_token}",
        "-e", "TFE_ADDRESS=${input:tfe_address}",
        "hashicorp/terraform-mcp-server:1.2.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"
      ]
    }
  }
}

<img alt="Install in VS Code (docker)" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Terraform%20MCP&color=0098FF">
<img alt="Install in VS Code Insiders (docker)" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Terraform%20MCP&color=24bfa5">

在 Cursor 中使用

将以下内容添加到您的 Cursor 配置 (~/.cursor/mcp.json) 或通过 Settings → Cursor Settings → MCP 添加：

<table>
<tr><th>Version 0.3.0+ 或更高版本</th><th>Version 0.2.3 或更低版本</th></tr>
<tr valign=top>
<td>

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

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

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=terraform&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCJoYXNoaWNvcnAvdGVycmFmb3JtLW1jcC1zZXJ2ZXIiXX0%3D">
<img alt="Add terraform MCP server to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" height="32" />
</a>

在 Claude Desktop / Amazon Q Developer / Kiro CLI 中的用法

关于在 Claude Desktop 中使用 MCP server 工具的更多信息，请参阅 用户文档。关于在 Amazon Q Developer 和 Kiro CLI 中使用 MCP server 的更多信息，请阅读相关文档。

<table>
<tr><th>Version 0.3.0+ 或更高版本</th><th>Version 0.2.3 或更低版本</th></tr>
<tr valign=top>
<td>

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

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

在 Claude Code 中使用

关于在 Claude Code 中使用和添加 MCP server 工具的更多信息，请参阅 user documentation

• 本地 (stdio) Transport
  sh

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

  - 远程 (streamable-http) 传输层
  sh

  # Run server (example)