Terraform MCP Server

Terraform MCP 服务

Terraform MCP 服务是一款 模型上下文协议（MCP）服务，可与 Terraform Registry 和 HCP Terraform API 无缝集成，为基础设施即代码（IaC）开发提供高级自动化和交互能力。

目录

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

**安全说明：**根据查询内容，MCP 服务可能会向 MCP 客户端和大模型公开某些 Terraform 数据。请勿将 MCP 服务用于不可信的 MCP 客户端或大模型。

**法律说明：**您对第三方 MCP 客户端/大模型的使用完全受该 MCP 客户端/大模型的使用条款约束，IBM 不对这类第三方工具的性能负责。IBM 明确否认对第三方 MCP 客户端/大模型作出的任何及所有保证，并且可能无法为解决由第三方工具导致的问题提供支持。

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

前提条件

1. 确保已安装并运行 Docker，以便在容器化环境中使用该服务。
2. 安装支持模型上下文协议（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 的作用本质上类似于面向编码 Agent 的 README：它为项目提供一个专门且固定的位置，用于提供上下文和说明，帮助 AI 编码 Agent 开展工作。同一个 AGENTS.md 文件可供不同的编码 Agent 使用。instructions/example-AGENTS.md 中提供了此类说明的示例。要使用它，请在 Terraform 配置所在目录中提交一个名为 AGENTS.md 的文件。

安装

在 Visual Studio Code 中使用

将以下 JSON 代码块添加到 VS Code 的用户设置（JSON）文件中。你可以按 Ctrl + Shift + P，然后输入 Preferences: Open User Settings (JSON) 来执行此操作。

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

{
  "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.4.1"
        ]
      }
    },
    "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": {
        "type": "http",
        "url": "https://mcp.terraform.io/mcp",
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

你也可以选择将类似的示例（即不带 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.4.1"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}

{
  "servers": {
    "terraform": {
      "type": "http",
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

在 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.4.1"
      ]
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

在 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.4.1"
      ]
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

注意： Claude Desktop 不支持通过配置文件配置远程 MCP 服务，请改用自定义连接器。

在 Claude Code 中使用

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

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

claude mcp add terraform -s user -t http \
  --header "Authorization: Bearer <<TFE_TOKEN>>" \
  https://mcp.terraform.io/mcp

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

注意： 对于需要身份验证的 HCP Terraform 或 Terraform Enterprise 工具，请将 TFE_ADDRESS 和 TFE_TOKEN 添加到 Docker 命令中。

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

[mcp_servers.terraform]
url = "https://mcp.terraform.io/mcp"
http_headers = { "Authorization" = "Bearer <<TFE_TOKEN>>" }

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

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      },
      "disabled": false
    }
  }
}

与 OpenCode 搭配使用

有关在 OpenCode 中使用和添加 MCP 服务的更多信息，请参阅用户文档。将服务添加到项目的 opencode.json 或全局配置文件 ~/.config/opencode/opencode.json 中。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "terraform": {
        "type": "local",
        "command": [
          "docker",
          "run",
          "-i",
          "--rm",
          "-e", "TFE_ADDRESS",
          "-e", "TFE_TOKEN",
          "hashicorp/terraform-mcp-server:1.4.1"
        ],
        "environment": {
          "TFE_ADDRESS": "{env:TFE_ADDRESS}",
          "TFE_TOKEN": "{env:TFE_TOKEN}"
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "terraform": {
        "type": "remote",
        "url": "https://mcp.terraform.io/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

Kubernetes（Helm）

可在 helm/terraform-mcp-server 下找到用于在 Kubernetes 上部署服务的 Helm chart。

从源代码安装

使用最新发布版本：

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

使用 main 分支：

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": "http",
        "url": "https://mcp.terraform.io/mcp",
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

在本地构建 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_provider_docs,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:

可用指标

会收集两类指标。 首先，将 HTTP mux 包装在 otelhttp.NewHandler(...) 中，以添加标准 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_provider_docs,get_provider_details,list_workspaces

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

传输支持

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

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。某些负载均衡器（包括 AWS Application Load Balancers）不会设置 X-Real-IP，因此使用这类负载均衡器时，该标头会直接来自客户端，不应使用。

可信任的跳数

使用 X-Forwarded-For 时，将 MCP_XFF_TRUSTED_HOPS 设置为你在服务前运行的代理数量。每个代理都会附加它收到请求时的来源地址，而不是自己的地址，因此客户端 IP 是从右侧数对应跳数的位置。其左侧的所有内容都由客户端发送，可能被伪造。

例如，若服务器位于单个负载均衡器（如 AWS ALB）之后，请设置 MCP_XFF_TRUSTED_HOPS=1。值为 198.51.100.7 的标头会解析为 198.51.100.7；值为 1.2.3.4, 198.51.100.7 的标头中，客户端自行发送了 1.2.3.4，也会解析为 198.51.100.7。当 MCP_XFF_TRUSTED_HOPS=2 且标头值为 1.2.3.4, 198.51.100.7, 10.0.0.5 时，服务会选择 198.51.100.7。如果跳数大于条目数，或选中的条目不是有效 IP，服务会回退到 RemoteAddr。

跳数设置过高会导致信任客户端提供的值；设置过低则会选中你自己基础设施中的地址。请将其设置为你实际运行的代理数量。

限制

• 如果请求携带多个 X-Forwarded-For 标头，服务会按顺序将它们合并，然后再选择条目。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.4.1

之后，用户通过标头传入各自的令牌进行连接，从而启用按用户实施的 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.4.1

对于 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.4.1"
      ]
    }
  }
}

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

如果你的环境不允许使用 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. 提交拉取请求

许可证

本项目采用 MPL-2.0 开源许可证。完整条款请参阅 LICENSE 文件。

安全

如需报告安全问题，请联系 [email protected]，或遵循我们的安全政策。

支持

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

如有一般问题或想参与讨论，请开启 GitHub Discussion。