hashicorp/terraform-mcp-server
GitHub: hashicorp/terraform-mcp-server
HashiCorp 官方的 Terraform MCP 服务器，让 AI 助手能够直接查询 Terraform Registry 并管理 HCP Terraform 及 TFE 工作区，为基础设施即代码开发提供智能化的上下文交互能力。
Stars: 1353 | Forks: 153
#
Terraform MCP Server
Terraform MCP Server 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 服务器，提供与 Terraform Registry API 的无缝集成，为 Infrastructure as Code (IaC) 开发实现高级自动化和交互功能。
## 功能
- **双重传输支持**：支持 Stdio 和 StreamableHTTP 传输，具有可配置的端点
- **Terraform Registry 集成**：直接与公共 Terraform Registry API 集成，支持 providers、modules 和 policies
- **HCP Terraform 与 Terraform Enterprise 支持**：完整的工作区管理、组织/项目列表以及私有 Registry 访问
- **工作区操作**：创建、更新、删除工作区，支持 variables、tags 和 run 管理
- **用于监控工具使用情况的 OTel 指标**：与 OpenTelemetry meters 集成，以在 Streamable HTTP 模式下跟踪工具调用量、延迟和失败。启用此功能后，还会公开默认的 HTTP 服务器指标
## 前置条件
1. 确保已安装并运行 [Docker](https://www.docker.com/)，以便在容器化环境中使用服务器。
2. 安装支持 Model Context Protocol (MCP) 的 AI 助手。
## 命令行选项
**环境变量：**
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `TFE_ADDRESS` | HCP Terraform 或 TFE 地址 | `"https://app.terraform.io"` |
| `TFE_TOKEN` | Terraform Enterprise API token | `""` (空) |
| `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_KEEP_ALIVE` | SSE 连接的 Keep-alive 间隔（例如，`30s`、`1m`）。设为 `0` 禁用 | `0` |
| `MCP_SESSION_MODE` | 会话模式：`stateful` 或 `stateless` | `stateful` |
| `MCP_ALLOWED_ORIGINS` | 允许的 CORS 源列表（以逗号分隔） | `""` (空) |
| `MCP_CORS_MODE` | CORS 模式：`strict`、`development` 或 `disabled` | `strict` |
| `MCP_TLS_CERT_FILE` | TLS 证书文件路径，非 localhost 部署时必需（例如 `/path/to/cert.pem`） | `""` (空) |
| `MCP_TLS_KEY_FILE` | TLS 密钥文件路径，非 localhost 部署时必需（例如 `/path/to/key.pem`）| `""` (空) |
| `MCP_RATE_LIMIT_GLOBAL` | 全局速率限制（格式：`rps:burst`） | `10:20` |
| `MCP_RATE_LIMIT_SESSION` | 每会话速率限制（格式：`rps:burst`） | `5:10` |
| `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` |
```
# Stdio 模式
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets
] [--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 ] [--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 服务器工具的更多信息，请参阅 [agent mode 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"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.2"
]
}
},
"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` 的文件中。这将允许您与他人共享配置。
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"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.2"
]
}
},
"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"
]
}
}
}
```
|
[
](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22terraform%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22hashicorp%2Fterraform-mcp-server%22%5D%7D)
[
](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22terraform%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22hashicorp%2Fterraform-mcp-server%22%5D%7D)
### 在 Cursor 中使用
将此内容添加到您的 Cursor 配置（`~/.cursor/mcp.json`）中，或通过 Settings → Cursor Settings → MCP 添加：
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "TFE_ADDRESS=<>",
"-e", "TFE_TOKEN=<>",
"hashicorp/terraform-mcp-server:0.5.2"
]
}
}
}
```
|
```
{
"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 服务器工具的更多信息，请参阅[用户文档](https://modelcontextprotocol.io/quickstart/user)。阅读有关在 [Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) 和 [Kiro CLI](https://kiro.dev/docs/mcp/) 中使用 MCP 服务器的更多信息。
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "TFE_ADDRESS=<>",
"-e", "TFE_TOKEN=<>",
"hashicorp/terraform-mcp-server:0.5.2"
]
}
}
}
```
|
```
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"hashicorp/terraform-mcp-server:0.2.3"
]
}
}
}
```
|
### 在 Claude Code 中使用
有关在 Claude Code 中使用和添加 MCP 服务器工具的更多信息，请参阅[用户文档](https://docs.claude.com/en/docs/claude-code/mcp)
- 本地 (`stdio`) 传输
```
claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server
```
- 远程 (`streamable-http`) 传输
```
# 运行 server（示例）
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 服务器工具的更多信息，请参阅 [Using MCP in Bob](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob)。
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "TFE_ADDRESS=<>",
"-e", "TFE_TOKEN=<>",
"hashicorp/terraform-mcp-server:0.5.2"
],
"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
```
使用 main 分支：
```
go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@main
```
| 0.3.0 及以上版本 | 0.2.3 及以下版本 |
|---|
|
```
{
"mcp": {
"servers": {
"terraform": {
"type": "stdio",
"command": "/path/to/terraform-mcp-server",
"env": {
"TFE_TOKEN": "<>"
},
}
}
}
}
```
|
```
{
"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
# 以 streamable-http 模式运行
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev
# 过滤 tools（可选）
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
```
4. （可选）在 HTTP 模式下测试连接
```
# 测试连接
curl http://localhost:8080/health
```
5. 您可以按如下方式在您的 AI 助手中使用它：
```
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"terraform-mcp-server:dev"
]
}
}
}
```
## 可用工具
[在此处查看可用工具 :link:](https://developer.hashicorp.com/terraform/docs/tools/mcp-server/reference#available-tools)
## 可用资源
[在此处查看可用资源 :link:](https://developer.hashicorp.com/terraform/docs/tools/mcp-server/reference#available-tools)
## 可用指标
收集两种类型的指标。
首先，通过使用 `otelhttp.NewHandler(...)` 封装 HTTP mux 来添加标准的 HTTP 服务器指标。这会发出：
1. http.server.request.body.size
2. http.server.response.body.size
3. http.server.request.duration
其次，MCP 服务器使用 MCP hooks (BeforeCallTool / AfterCallTool) 记录围绕工具执行的自定义工具指标。这些会发出：
1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds
### 工具过滤
使用 `--toolsets`（分组）或 `--tools`（单个）控制可用工具：
```
# 启用 tool 组（默认：registry）
terraform-mcp-server --toolsets=registry,terraform
# 仅启用特定 tools
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 请求和 Server-Sent Events (SSE) 流。这是用于远程/分布式设置的推荐传输方式。
**功能：**
- **端点**：`http://{hostname}:8080/mcp`
- **健康检查**：`http://{hostname}:8080/health`
- **环境配置**：设置 `TRANSPORT_MODE=http` 或 `TRANSPORT_PORT=8080` 以启用
## 会话模式
Terraform MCP Server 在使用 StreamableHTTP 传输时支持两种会话模式：
- **有状态模式（默认）**：在请求之间维护会话状态，支持上下文感知操作。
- **无状态模式**：每个请求都独立处理，不维护会话状态，这对于高可用性部署或在使用负载均衡器时非常有用。
要启用无状态模式，请设置环境变量：
```
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.2
```
对于 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.2"
]
}
}
}
```
**替代方案：直接运行二进制文件**
如果您的环境中不允许使用 Docker，您可以直接安装并运行服务器二进制文件，它将使用您系统的证书库：
```
go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
terraform-mcp-server stdio
```
## 开发
### 前置条件
- Go（查看 [go.mod](./go.mod) 文件以获取特定版本）
- Docker（可选，用于容器构建）
### 可用的 Make 命
| 命令 | 描述 |
|---------|-------------|
| `make build` | 构建二进制文件 |
| `make test` | 运行所有测试 |
| `make test-e2e` | 运行端到端测试 |
| `make docker-build` | 构建 Docker 镜像 |
| `make run-http` | 在本地运行 HTTP 服务器 |
| `make docker-run-http` | 在 Docker 中运行 HTTP 服务器 |
| `make test-http` | 测试 HTTP 健康检查端点 |
| `make clean` | 移除构建产物 |
| `make help` | 显示所有可用命令 |
## 贡献
1. Fork 本仓库
2. 创建您的功能分支
3. 进行更改
4. 运行测试
5. 提交 Pull Request
## 许可证
本项目采用 MPL-2.0 开源许可证条款授权。有关完整条款，请参阅 [LICENSE](./LICENSE) 文件。
## 安全
如有安全问题，请联系 security@hashicorp.com 或遵循我们的[安全政策](https://www.hashicorp.com/en/trust/security/vulnerability-management)。
## 支持
对于错误报告和功能请求，请在 GitHub 上开启一个 Issue。
对于一般性问题和讨论，请开启一个 GitHub Discussion。标签：AI助手集成, API集成, CISA项目, DNS解析, Docker, EC2, ECS, EVTX分析, GET参数, Go语言, HCP Terraform, IaC, IT运维, MCP, MCP服务器, Model Context Protocol, NIDS, OpenTelemetry, OTel, Socks5代理, Stdio, Terraform, Terraform Enterprise, Terraform Registry, 云计算, 可观测性, 大语言模型集成, 安全防御评估, 容器化, 工作区管理, 开源项目, 性能监控, 日志审计, 用户代理, 程序破解, 网络调试, 自动化, 规则引擎, 请求拦截