Terraform MCP Server

Terraform MCP Server

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

目录

功能特性

• 双传输支持：支持 Stdio 和 StreamableHTTP 两种传输方式，并提供可配置的端点
• Terraform Registry 集成：直接集成公共 Terraform Registry API，支持 providers、modules 和 policies
• HCP Terraform 与 Terraform Enterprise 支持：完整的工作区管理、组织/项目列表以及私有注册表访问
• 工作区操作：创建工作区、更新、删除，支持变量、标签和运行管理
• 用于监控工具使用的 OTel 指标：集成开放遥测仪表，在 Streamable HTTP 模式下跟踪工具调用量、延迟和失败情况。启用该功能时还会暴露默认的 HTTP 服务器指标

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

法律提示： 您对第三方 MCP 客户端/LLM 的使用仅受该等 MCP/LLM 使用条款的约束，IBM 不对该等第三方工具的性能负责。IBM 明确否认对第三方 MCP 客户端/LLM 的任何及所有保证和责任，并且可能无法提供支持来解决由第三方工具引起的问题。

注意： MCP 服务器提供的输出和建议是动态生成的，可能因查询、模型和所连接的 MCP 客户端而异。用户在实施前应全面审查所有输出/建议，以确保其符合组织的安全最佳实践、成本效率目标和合规要求。

前提条件

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

命令行选项

环境变量：

# 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 服务器的默认指令位于 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 的 agent mode 文档 中使用 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:1.3.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:1.3.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:1.3.0"
      ]
    }
  }
}

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

与 Claude Desktop / Amazon Q Developer / Kiro CLI 一起使用

更多关于在 Claude Desktop 中使用 MCP 服务器工具的信息，请参阅用户文档。更多关于在 Amazon Q Developer 和 Kiro CLI 中使用 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:1.3.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）传输

# 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

与 Codex CLI 一起使用

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

注意： 对于经过认证的 HCP Terraform 或 Terraform Enterprise 工具，请在 Docker 命令中添加 TFE_ADDRESS 和 TFE_TOKEN。

• 本地（stdio）传输

codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

• 远程（streamable-http）传输

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

# Add to Codex
codex mcp add terraform --url 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:1.3.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 镜像，您可以在以下配置中使用它。

# 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

注意： 在 Docker 中运行时，您应该设置 TRANSPORT_HOST=0.0.0.0 以允许从容器外部进行连接。

4. （可选）在 http 模式下测试连接

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

5. 您可以按以下方式在您的 AI 助手中使用它：

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

可用工具

点击此处查看可用工具 :link:

可用资源

点击此处查看可用资源 :link:

可用指标

收集两种类型的指标。 首先，通过使用 otelhttp.NewHandler(...) 包装 HTTP mux 来添加标准 HTTP 服务器指标。这会发出：

1. http.server.request.body.size
2. http.server.response.body.size
3. http.server.request.duration

其次，MCP 服务器使用 MCP 钩子（BeforeCallTool / AfterCallTool）在工具执行期间记录自定义工具指标。这些指标包括：

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

工具过滤

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

# 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

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

传输支持

Terraform MCP Server 支持多种传输协议：

1. Stdio 传输（默认）

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

2. StreamableHTTP 传输

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

特性：

• 端点：http://{hostname}:8080/mcp
• 健康检查：http://{hostname}:8080/health
• 环境配置：设置 TRANSPORT_MODE=http 或 TRANSPORT_PORT=8080 以启用
• 组织允许列表：将 MCP_ORGANIZATION_ALLOWLIST 或 --organization-allowlist 设置为允许的 HCP Terraform 组织名称的 CSV 列表

会话模式

Terraform MCP Server 在使用 StreamableHTTP 传输时支持两种会话模式：

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

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

export MCP_SESSION_MODE=stateless

集中式部署的令牌传递

当为多个用户集中运行 MCP 服务器（StreamableHTTP 模式）时，每个用户可以通过 HTTP 头传递自己的 Terraform 令牌以进行 RBAC 强制执行。这允许单个服务器实例为具有不同权限的多个用户提供服务。

当配置了 MCP_ORGANIZATION_ALLOWLIST 或 --organization-allowlist 时，允许列表必须是 HCP Terraform 组织名称的 CSV 列表。服务器要求 Authorization: Bearer <token>，并且除非该令牌可以访问 CSV 允许列表中的至少一个组织，否则拒绝请求。如果请求还包含 TFE_TOKEN 头，则 bearer 令牌优先，确保通过允许列表验证的令牌是用于 Terraform API 请求的令牌。组织名称匹配不区分大小写。如果配置的 CSV 值解析为零个组织名称，服务器将以格式错误的组织允许列表错误退出。

客户端 IP 转发

当在代理或负载均衡器后面集中运行 MCP 服务器时，您可以通过 X-Forwarded-For 头将原始客户端的 IP 转发到 HCP Terraform / TFE。此功能默认关闭，必须通过 MCP_FORWARD_CLIENT_IP=true 启用。

启用后，服务器根据 MCP_REMOTE_IP_METHOD 获取客户端 IP：

信任模型

X-Forwarded-For 和 X-Real-IP 由客户端和中间代理设置，因此除非服务器前面的受信任代理覆盖它们，否则它们可能被伪造。因此，默认值为 RemoteAddr，它只信任服务器直接连接的对等方。仅在服务器位于您控制的、设置这些头的代理后面时，才启用 X-Real-IP 或 X-Forwarded-For。

受信任的跳数

使用 X-Forwarded-For 时，MCP_XFF_TRUSTED_HOPS 是您在服务器和互联网之间操作的代理数量。跳数从链的右侧开始计数，因为每个代理都会追加它收到请求的地址，最右侧的条目由最靠近服务器的代理设置。服务器跳过那么多受信任的条目，并取左侧的下一个条目。

例如，使用 MCP_XFF_TRUSTED_HOPS=1 和头 200.1.2.3, 10.1.1.10，服务器选择 200.1.2.3。使用 MCP_XFF_TRUSTED_HOPS=2 和 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1，它选择 200.1.2.3。如果跳数大于条目数，或者所选条目不是有效 IP，服务器将回退到 RemoteAddr。

将跳数设置得太低将信任客户端提供的值；设置得太高将信任您自己基础设施中更远的地址。将其设置为您运行的代理的确切数量。

限制

• 服务器只读取请求上的第一个 X-Forwarded-For 头。请求携带多个 X-Forwarded-For 头是有效的，但 Go 的标准库只返回第一个，服务器不会合并它们。如果您的代理链发出多个头，请将其配置为发出单个组合的 X-Forwarded-For 头。
• 支持 IPv4 和 IPv6 地址。不是有效 IP 的值将被拒绝，服务器将回退到 RemoteAddr。

从早期版本迁移

早期版本在头存在时使用最左侧的 X-Forwarded-For 值，无需配置。这是不安全的，因为最左侧的值最容易伪造。现在默认值为 RemoteAddr。如果您在代理后面运行服务器并依赖 X-Forwarded-For 转发到 HCP Terraform / TFE，请将 MCP_REMOTE_IP_METHOD=X-Forwarded-For 和 MCP_XFF_TRUSTED_HOPS 设置为您操作的代理数量。

支持的请求头

示例：curl

# Using TFE_TOKEN header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "TFE_TOKEN: your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

# Using Authorization Bearer header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

安全注意事项

• 客户端无法设置 TFE_ADDRESS。 在 streamable-http 模式下，Terraform 地址仅从服务器端的 TFE_ADDRESS 环境变量（或默认值）获取。尝试通过 HTTP 头或查询参数设置 TFE_ADDRESS 的请求将被拒绝并返回 403。这可以防止客户端将请求以及 Authorization 令牌重定向到恶意服务器。
• 托管部署标识： 设置 TF_MCP_SHARED_SECRET 会在每个 HCP Terraform / TFE 请求中发送该值作为 X-Tf-Mcp-Secret 头，使后端能够识别来自已知托管部署的请求（例如，应用 IP 允许列表）。这是一个在头中发送的静态机密，因此请仅在 TLS 上使用它，并将该值视为凭据。
• 切勿在查询参数中传递令牌 - 服务器将拒绝此类请求并返回 400 错误。
• 集中部署时始终使用 TLS（MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE）以保护传输中的令牌。
• 配置 MCP_ALLOWED_ORIGINS 以限制哪些客户端可以连接。

集中式部署示例

# Start server centrally (no token set server-side)
docker run -p 8080:8080 \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e TFE_ADDRESS=https://tfe.company.com \
  -e MCP_TLS_CERT_FILE=/certs/server.pem \
  -e MCP_TLS_KEY_FILE=/certs/server-key.pem \
  -e MCP_ALLOWED_ORIGINS=https://ide.company.com \
  -e MCP_ORGANIZATION_ALLOWLIST=team-alpha,team-beta \
  -v /path/to/certs:/certs \
  hashicorp/terraform-mcp-server:1.3.0

然后，用户通过头传递各自的令牌进行连接，从而启用按用户的 RBAC 强制执行。

故障排除

企业代理 / 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:1.3.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:1.3.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. 复刻（Fork）本仓库
2. 创建您的功能分支
3. 进行您的更改
4. 运行测试
5. 提交拉取请求（Pull Request）

许可证

本项目根据 MPL-2.0 开源许可证的条款进行许可。请参阅 LICENSE 文件以获取完整条款。

安全

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

支持

如需报告错误或请求新功能，请在 GitHub 上开启一个 Issue。

如有一般性问题或讨论，请在 GitHub 上开启一个 Discussion。