Terraform MCP Server - AI驱动的基础设施即代码管理

Posted on

Terraform MCP Server - AI驱动的基础设施即代码管理

HashiCorp 官方实现 | Stars: 986 | Go | MPL-2.0

概述

Terraform MCP Server 是 HashiCorp 官方提供的 Model Context Protocol 实现，为 AI 助手提供与 Terraform 生态系统的无缝集成。它支持访问 Terraform 公共注册表、管理 HCP Terraform 和 Terraform Enterprise 工作空间，以及执行基础设施即代码（IaC）的各种操作。

该服务器提供了30+ 个专业工具，涵盖 Provider/Module 搜索、工作空间管理、变量配置、运行管理等核心功能。支持双传输协议（Stdio 和 StreamableHTTP），可灵活部署在本地开发环境或企业生产环境中。特别适合需要智能化基础设施管理、自动化运维、策略合规的 DevOps 和 Platform 团队。

核心特性

  • ✅ HashiCorp 官方实现，与 Terraform 生态深度集成
  • 🛠️ 30+ 专业工具，覆盖注册表查询和工作空间管理
  • 🎯 双传输协议支持（Stdio / StreamableHTTP）
  • 📊 完整的 HCP Terraform 集成
  • 🌐 公共和私有注册表支持
  • 🔌 兼容多种 MCP 客户端（Claude Desktop、VS Code、Cursor、Gemini）
  • 🚀 有状态/无状态会话模式
  • 🔒 企业级安全特性（TLS、CORS、速率限制）
  • ⚡ 变量集和标签管理
  • 🎛️ 运行操作控制（Plan/Apply/Refresh）

工具列表

注册表工具（Registry Tools）

这些工具始终可用，无需 TFE Token：

1. resolve_provider_doc_id

功能：解析 Terraform Provider 文档 ID

参数：

  • provider (string, 必需) - Provider 名称，格式：namespace/provider-name

示例：

1
2
3
{
  "provider": "hashicorp/aws"
}

2. get_provider_docs

功能：获取 Terraform Provider 的完整文档

参数：

  • provider (string, 必需) - Provider 名称
  • doc_type (string, 可选) - 文档类型（resources/data-sources/functions/guides）

示例：

1
2
3
4
{
  "provider": "hashicorp/aws",
  "doc_type": "resources"
}

3. get_latest_provider_version

功能：获取 Provider 的最新版本信息

参数：

  • provider (string, 必需) - Provider 名称，格式：namespace/provider-name

示例：

1
2
3
{
  "provider": "hashicorp/kubernetes"
}

4. search_modules

功能：在 Terraform 公共注册表中搜索模块

参数：

  • query (string, 必需) - 搜索查询字符串

示例：

1
2
3
{
  "query": "vpc aws"
}

返回示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Available Terraform Modules (top matches) for vpc aws

Each result includes:
- module_id: The module ID (format: namespace/name/provider-name/module-version)
- Name: The name of the module
- Description: A short description of the module
- Downloads: The total number of times the module has been downloaded
- Verified: Verification status of the module
- Published: The date and time when the module was published

---

- module_id: terraform-aws-modules/vpc/aws
- Name: vpc
- Description: Terraform module which creates VPC resources on AWS
- Downloads: 45000000
- Verified: true
- Published: 2025-09-15T10:30:00Z
---

5. get_module_details

功能：获取 Terraform Module 的详细信息

参数：

  • module_id (string, 必需) - 模块 ID，格式：namespace/name/provider

示例：

1
2
3
{
  "module_id": "terraform-aws-modules/vpc/aws"
}

6. get_latest_module_version

功能：获取 Module 的最新版本信息

参数：

  • module_id (string, 必需) - 模块 ID，格式：namespace/name/provider

示例：

1
2
3
{
  "module_id": "terraform-aws-modules/vpc/aws"
}

7. search_policies

功能：搜索 Sentinel 策略（用于合规和治理）

参数：

  • query (string, 必需) - 搜索查询字符串

示例：

1
2
3
{
  "query": "aws s3 encryption"
}

8. get_policy_details

功能：获取 Sentinel 策略的详细信息

参数：

  • policy_id (string, 必需) - 策略 ID

示例：

1
2
3
{
  "policy_id": "hashicorp/example-policy"
}

HCP Terraform / TFE 工具

这些工具需要配置 TFE_TOKEN 环境变量：

9. list_terraform_orgs

功能：列出所有 Terraform 组织

参数：无

示例：

1
{}

10. list_terraform_projects

功能：列出组织中的所有项目

参数：

  • organization (string, 必需) - 组织名称

示例：

1
2
3
{
  "organization": "my-company"
}

11. list_workspaces

功能：列出组织中的所有工作空间

参数：

  • organization (string, 必需) - 组织名称
  • project_id (string, 可选) - 项目 ID，用于过滤

示例：

1
2
3
4
{
  "organization": "my-company",
  "project_id": "prj-abc123"
}

12. get_workspace_details

功能：获取工作空间的详细信息

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称

示例：

1
2
3
4
{
  "organization": "my-company",
  "workspace": "production-infra"
}

13. create_workspace

功能：创建新的 Terraform 工作空间

参数：

  • organization (string, 必需) - 组织名称
  • workspace_name (string, 必需) - 工作空间名称
  • project_id (string, 可选) - 项目 ID
  • terraform_version (string, 可选) - Terraform 版本
  • auto_apply (boolean, 可选) - 是否自动应用

示例：

1
2
3
4
5
6
{
  "organization": "my-company",
  "workspace_name": "staging-app",
  "terraform_version": "1.6.0",
  "auto_apply": false
}

14. update_workspace

功能：更新现有工作空间的配置

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称
  • attributes (object, 必需) - 要更新的属性

示例：

1
2
3
4
5
6
7
8
{
  "organization": "my-company",
  "workspace": "production-infra",
  "attributes": {
    "auto_apply": true,
    "terraform_version": "1.7.0"
  }
}

15. delete_workspace_safely

功能：安全地删除工作空间（需要 ENABLE_TF_OPERATIONS=true）

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称

示例：

1
2
3
4
{
  "organization": "my-company",
  "workspace": "deprecated-workspace"
}

注意：此工具默认禁用，需要显式启用 ENABLE_TF_OPERATIONS 环境变量。

16. search_private_providers

功能：搜索私有 Provider

参数：

  • organization (string, 必需) - 组织名称
  • query (string, 可选) - 搜索查询

示例：

1
2
3
4
{
  "organization": "my-company",
  "query": "custom"
}

17. get_private_provider_details

功能：获取私有 Provider 的详细信息

参数：

  • organization (string, 必需) - 组织名称
  • registry_name (string, 必需) - 注册表名称
  • provider_name (string, 必需) - Provider 名称

示例：

1
2
3
4
5
{
  "organization": "my-company",
  "registry_name": "private",
  "provider_name": "custom-aws"
}

18. search_private_modules

功能：搜索私有 Module

参数：

  • organization (string, 必需) - 组织名称
  • query (string, 可选) - 搜索查询

示例：

1
2
3
4
{
  "organization": "my-company",
  "query": "networking"
}

19. get_private_module_details

功能：获取私有 Module 的详细信息

参数：

  • organization (string, 必需) - 组织名称
  • registry_name (string, 必需) - 注册表名称
  • module_name (string, 必需) - Module 名称
  • provider (string, 必需) - Provider 名称

示例：

1
2
3
4
5
6
{
  "organization": "my-company",
  "registry_name": "private",
  "module_name": "vpc",
  "provider": "aws"
}

20. create_workspace_tags

功能：为工作空间创建标签

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称
  • tags (array, 必需) - 标签列表

示例：

1
2
3
4
5
{
  "organization": "my-company",
  "workspace": "production-infra",
  "tags": ["production", "critical", "team-platform"]
}

21. read_workspace_tags

功能：读取工作空间的标签

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称

示例：

1
2
3
4
{
  "organization": "my-company",
  "workspace": "production-infra"
}

22. list_runs

功能：列出工作空间的运行记录

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称

示例：

1
2
3
4
{
  "organization": "my-company",
  "workspace": "production-infra"
}

23. create_run

功能：创建 Terraform 运行（Plan 或 Apply）

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称
  • message (string, 可选) - 运行消息
  • operation (string, 可选) - 操作类型（plan_and_apply / refresh_state）

示例：

1
2
3
4
5
6
{
  "organization": "my-company",
  "workspace": "production-infra",
  "message": "Deploy new feature",
  "operation": "plan_and_apply"
}

行为：

  • 默认模式：创建 Plan，不会自动 Apply（安全模式）
  • ENABLE_TF_OPERATIONS=true 时：可以创建 Plan 并自动 Apply

24. action_run

功能：对运行执行操作（需要 ENABLE_TF_OPERATIONS=true）

参数：

  • run_id (string, 必需) - 运行 ID
  • action (string, 必需) - 操作类型（apply / discard / cancel）

示例：

1
2
3
4
{
  "run_id": "run-abc123",
  "action": "apply"
}

注意：此工具默认禁用，需要显式启用 ENABLE_TF_OPERATIONS 环境变量。

25. get_run_details

功能：获取运行的详细信息

参数：

  • run_id (string, 必需) - 运行 ID

示例：

1
2
3
{
  "run_id": "run-abc123"
}

26. list_variable_sets

功能：列出变量集

参数：

  • organization (string, 必需) - 组织名称

示例：

1
2
3
{
  "organization": "my-company"
}

27. create_variable_set

功能：创建变量集

参数：

  • organization (string, 必需) - 组织名称
  • name (string, 必需) - 变量集名称
  • description (string, 可选) - 描述
  • global (boolean, 可选) - 是否全局应用

示例：

1
2
3
4
5
6
{
  "organization": "my-company",
  "name": "aws-credentials",
  "description": "AWS access credentials for all workspaces",
  "global": true
}

28. create_variable_in_variable_set

功能：在变量集中创建变量

参数：

  • variable_set_id (string, 必需) - 变量集 ID
  • key (string, 必需) - 变量键
  • value (string, 必需) - 变量值
  • category (string, 必需) - 变量类别（terraform / env）
  • sensitive (boolean, 可选) - 是否敏感

示例：

1
2
3
4
5
6
7
{
  "variable_set_id": "varset-abc123",
  "key": "AWS_ACCESS_KEY_ID",
  "value": "AKIAIOSFODNN7EXAMPLE",
  "category": "env",
  "sensitive": true
}

29. delete_variable_in_variable_set

功能：从变量集中删除变量

参数：

  • variable_set_id (string, 必需) - 变量集 ID
  • variable_id (string, 必需) - 变量 ID

示例：

1
2
3
4
{
  "variable_set_id": "varset-abc123",
  "variable_id": "var-xyz789"
}

30. attach_variable_set_to_workspaces

功能：将变量集附加到工作空间

参数：

  • variable_set_id (string, 必需) - 变量集 ID
  • workspace_ids (array, 必需) - 工作空间 ID 列表

示例：

1
2
3
4
{
  "variable_set_id": "varset-abc123",
  "workspace_ids": ["ws-123", "ws-456", "ws-789"]
}

31. detach_variable_set_from_workspaces

功能：从工作空间分离变量集

参数：

  • variable_set_id (string, 必需) - 变量集 ID
  • workspace_ids (array, 必需) - 工作空间 ID 列表

示例：

1
2
3
4
{
  "variable_set_id": "varset-abc123",
  "workspace_ids": ["ws-123"]
}

32. list_workspace_variables

功能：列出工作空间的变量

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称

示例：

1
2
3
4
{
  "organization": "my-company",
  "workspace": "production-infra"
}

33. create_workspace_variable

功能：在工作空间中创建变量

参数：

  • organization (string, 必需) - 组织名称
  • workspace (string, 必需) - 工作空间名称
  • key (string, 必需) - 变量键
  • value (string, 必需) - 变量值
  • category (string, 必需) - 变量类别（terraform / env）
  • sensitive (boolean, 可选) - 是否敏感

示例：

1
2
3
4
5
6
7
8
{
  "organization": "my-company",
  "workspace": "production-infra",
  "key": "instance_type",
  "value": "t3.large",
  "category": "terraform",
  "sensitive": false
}

配置方式

环境变量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# === 核心配置 ===
# HCP Terraform / TFE 地址
TFE_ADDRESS=https://app.terraform.io

# Terraform Enterprise API Token（必需，用于访问 TFE 工具）
TFE_TOKEN=your-token-here

# 跳过 TLS 验证（开发环境）
TFE_SKIP_TLS_VERIFY=false

# === 传输配置 ===
# 传输模式：stdio（默认）或 streamable-http
TRANSPORT_MODE=stdio

# HTTP 服务器配置（仅 streamable-http 模式）
TRANSPORT_HOST=127.0.0.1
TRANSPORT_PORT=8080
MCP_ENDPOINT=/mcp

# === 会话配置 ===
# 会话模式：stateful（默认）或 stateless
MCP_SESSION_MODE=stateful

# === 安全配置 ===
# CORS 允许的源（逗号分隔）
MCP_ALLOWED_ORIGINS=http://localhost:3000,https://app.example.com

# CORS 模式：strict（默认）/ development / disabled
MCP_CORS_MODE=strict

# TLS 配置（非 localhost 部署必需）
MCP_TLS_CERT_FILE=/path/to/cert.pem
MCP_TLS_KEY_FILE=/path/to/key.pem

# === 速率限制 ===
# 全局速率限制（格式：rps:burst）
MCP_RATE_LIMIT_GLOBAL=10:20

# 每会话速率限制（格式：rps:burst）
MCP_RATE_LIMIT_SESSION=5:10

# === 功能开关 ===
# 启用需要显式批准的工具（delete_workspace_safely, action_run）
ENABLE_TF_OPERATIONS=false

Claude Desktop 配置

在 ~/.config/claude/claude_desktop_config.json 中添加（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TFE_ADDRESS=https://app.terraform.io",
        "-e",
        "TFE_TOKEN=your-token-here",
        "hashicorp/terraform-mcp-server:0.3.0"
      ]
    }
  }
}

VS Code 配置

在 VS Code 的 User Settings (JSON) 中添加（Ctrl+Shift+P → Preferences: Open User Settings (JSON)）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "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.3.0"
        ]
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "tfe_token",
        "description": "Terraform API Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "tfe_address",
        "description": "Terraform Address",
        "password": false
      }
    ]
  }
}

或在项目的 .vscode/mcp.json 文件中配置（团队共享）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "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.3.0"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}

Cursor 配置

在 ~/.cursor/mcp.json 或通过 Settings → Cursor Settings → MCP 添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TFE_ADDRESS=https://app.terraform.io",
        "-e",
        "TFE_TOKEN=your-token-here",
        "hashicorp/terraform-mcp-server:0.3.0"
      ]
    }
  }
}

Claude Code 配置

Stdio 传输（本地）

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

StreamableHTTP 传输（远程）

1
2
3
4
5
6
7
8
# 1. 启动服务器
docker run -p 8080:8080 --rm \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  hashicorp/terraform-mcp-server

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

Gemini 配置

创建 ~/.gemini/.env 文件：

1
2
3
# ~/.gemini/.env
TFE_ADDRESS=https://app.terraform.io
TFE_TOKEN=your-token-here

安装并运行：

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

Docker 部署

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Stdio 模式（本地开发）
docker run -i --rm \
  -e TFE_TOKEN="your-token" \
  hashicorp/terraform-mcp-server

# StreamableHTTP 模式（远程部署）
docker run -p 8080:8080 --rm \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e TFE_TOKEN="your-token" \
  -e MCP_ALLOWED_ORIGINS="https://your-app.com" \
  -e MCP_TLS_CERT_FILE=/certs/cert.pem \
  -e MCP_TLS_KEY_FILE=/certs/key.pem \
  -v /path/to/certs:/certs \
  hashicorp/terraform-mcp-server

从源码安装

1
2
3
4
5
# 安装最新版本
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

配置示例（VS Code）：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server",
        "env": {
          "TFE_TOKEN": "your-token-here"
        }
      }
    }
  }
}

使用场景

1. 智能化 Provider 和 Module 搜索

通过自然语言查询快速找到合适的 Terraform Providers 和 Modules。

示例对话：

1
2
用户: "我需要在 AWS 上创建一个 VPC，推荐一个成熟的模块"
AI: 搜索并推荐 terraform-aws-modules/vpc/aws，包含使用示例

技术流程：

  1. 使用 search_modules 工具搜索关键词
  2. 使用 get_module_details 获取详细信息
  3. 使用 get_latest_module_version 确认最新版本
  4. AI 生成配置示例

2. 工作空间自动化管理

使用自然语言命令管理 Terraform 工作空间，无需手动登录 HCP Terraform。

示例对话：

1
2
3
4
用户: "创建一个名为 staging-api 的工作空间，使用 Terraform 1.7.0"
AI: 调用 create_workspace 工具创建工作空间
用户: "给这个工作空间打上 staging 和 api 标签"
AI: 调用 create_workspace_tags 添加标签

技术流程：

  1. create_workspace - 创建工作空间
  2. create_workspace_tags - 添加标签
  3. create_workspace_variable - 配置变量
  4. get_workspace_details - 验证配置

3. 策略合规检查

集成 Sentinel 策略，通过 AI 助手进行合规性检查。

示例对话：

1
2
用户: "我需要确保所有 S3 Bucket 都启用加密，有什么策略推荐？"
AI: 使用 search_policies 搜索 "s3 encryption"，返回相关策略

技术流程：

  1. search_policies - 搜索策略
  2. get_policy_details - 获取策略详情
  3. AI 解释策略内容和使用方法

4. 变量和配置管理

智能管理变量集和工作空间变量，确保配置一致性。

示例对话：

1
2
3
4
5
6
用户: "创建一个全局变量集用于 AWS 凭据"
AI: 调用 create_variable_set
用户: "添加 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY"
AI: 调用 create_variable_in_variable_set（标记为 sensitive）
用户: "把这个变量集应用到所有生产环境工作空间"
AI: 调用 attach_variable_set_to_workspaces

技术流程：

  1. create_variable_set - 创建变量集
  2. create_variable_in_variable_set - 添加敏感变量
  3. list_workspaces - 查找目标工作空间
  4. attach_variable_set_to_workspaces - 批量应用

5. CI/CD 集成

在 CI/CD 流水线中集成 MCP，实现智能化的基础设施部署。

示例流程：

1
2
3
4
5
6
7
8
9
10
# GitHub Actions 示例
- name: Trigger Terraform Run
  run: |
    # 通过 MCP 创建运行
    # create_run 工具会返回 run_id

- name: Monitor Run Status
  run: |
    # 使用 get_run_details 监控运行状态
    # 等待运行完成或失败

技术流程：

  1. create_run - 创建 Plan
  2. get_run_details - 监控状态
  3. action_run - Apply（如果启用 ENABLE_TF_OPERATIONS）

6. 文档即代码

通过 AI 助手自动查询和生成 Terraform 文档。

示例对话：

1
2
用户: "AWS Provider 的 EC2 实例资源有哪些参数？"
AI: 使用 get_provider_docs 获取 aws_instance 文档

技术架构

传输模式

1
2
3
4
5
6
7
8
9
10
11
┌─────────────────┐       ┌──────────────────┐
│  MCP Client     │       │  Terraform       │
│  (Claude/VSCode)│◄─────►│  MCP Server      │
└─────────────────┘       └──────────────────┘
                                   │
                  ┌────────────────┼────────────────┐
                  │                │                │
           ┌──────▼─────┐   ┌─────▼──────┐  ┌─────▼──────┐
           │  Stdio     │   │ Streamable │  │  HTTP      │
           │  Transport │   │ HTTP       │  │  Transport │
           └────────────┘   └────────────┘  └────────────┘

会话模式

有状态模式（Stateful，默认）

1
2
3
4
客户端请求 → 会话上下文 → 工具执行 → 状态保持
              ↓
         TFE Client 复用
         上下文信息保持

优势：

  • 上下文感知
  • 减少重复认证
  • 性能更好

适用场景：

  • 单实例部署
  • 开发环境
  • 交互式操作

无状态模式（Stateless）

1
每个请求独立处理 → 无会话依赖 → 适合负载均衡

优势：

  • 高可用
  • 负载均衡友好
  • 水平扩展

适用场景：

  • 生产环境
  • 分布式部署
  • 多副本运行

工具分类架构

1
2
3
4
5
6
7
8
9
10
11
12
13
Terraform MCP Server
├── Registry Tools（注册表工具）
│   ├── Provider 查询
│   ├── Module 搜索
│   └── Policy 检索
├── TFE Tools（企业工具）
│   ├── 组织管理
│   ├── 工作空间管理
│   ├── 变量管理
│   └── 运行管理
└── Dynamic Tools（动态工具）
    ├── 基于会话状态注册
    └── 需要 TFE Token

安全架构

1
2
3
4
5
6
7
8
9
10
11
12
┌──────────────────────────────────────────┐
│            安全层                         │
├──────────────────────────────────────────┤
│  TLS 加密 (MCP_TLS_CERT_FILE/KEY_FILE)  │
│  CORS 验证 (MCP_ALLOWED_ORIGINS)         │
│  速率限制 (MCP_RATE_LIMIT_*)             │
│  操作控制 (ENABLE_TF_OPERATIONS)         │
└──────────────────────────────────────────┘
                   ↓
┌──────────────────────────────────────────┐
│          MCP 服务器核心                   │
└──────────────────────────────────────────┘

与其他 MCP 服务器对比

特性 Terraform MCP AWS MCP Kubernetes MCP
IaC 支持 ✅ 原生 Terraform ❌ 无 ❌ 无
工作空间管理 ✅ 完整 ❌ 无 ✅ 命名空间
注册表集成 ✅ 公共+私有 ❌ 无 ❌ 无
多云支持 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐
策略引擎 ✅ Sentinel ✅ IAM ✅ RBAC
企业集成 ✅ HCP/TFE ✅ AWS Organizations ✅ 多集群
适用场景 IaC、多云管理 AWS 资源管理 K8s 管理

最佳实践

1. 安全配置

1
2
3
4
5
6
7
8
9
10
11
12
13
# 使用环境变量管理 Token，避免硬编码
export TFE_TOKEN=$(cat ~/.terraform.d/credentials.tfrc.json | jq -r '.credentials."app.terraform.io".token')

# 生产环境必须启用 TLS
export MCP_TLS_CERT_FILE=/etc/ssl/certs/terraform-mcp.crt
export MCP_TLS_KEY_FILE=/etc/ssl/private/terraform-mcp.key

# 配置严格的 CORS
export MCP_ALLOWED_ORIGINS="https://production-app.company.com"
export MCP_CORS_MODE="strict"

# 谨慎使用破坏性操作
export ENABLE_TF_OPERATIONS=false  # 默认禁用

2. 会话模式选择

1
2
3
4
5
# 开发环境：有状态模式（默认）
export MCP_SESSION_MODE=stateful

# 生产环境：无状态模式 + 负载均衡
export MCP_SESSION_MODE=stateless

3. 速率限制配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 根据负载调整速率限制
# 格式：rps:burst

# 轻量级使用
export MCP_RATE_LIMIT_GLOBAL=5:10
export MCP_RATE_LIMIT_SESSION=2:5

# 中等负载
export MCP_RATE_LIMIT_GLOBAL=10:20
export MCP_RATE_LIMIT_SESSION=5:10

# 高负载
export MCP_RATE_LIMIT_GLOBAL=20:50
export MCP_RATE_LIMIT_SESSION=10:20

4. 变量管理最佳实践

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 使用变量集管理共享凭据
# 1. 创建组织级变量集
# 2. 标记敏感变量为 sensitive=true
# 3. 使用全局变量集减少重复

# 示例：AWS 凭据管理
{
  "variable_set_name": "aws-credentials",
  "global": true,
  "variables": [
    {
      "key": "AWS_ACCESS_KEY_ID",
      "category": "env",
      "sensitive": true
    },
    {
      "key": "AWS_SECRET_ACCESS_KEY",
      "category": "env",
      "sensitive": true
    }
  ]
}

5. 工作空间标签策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 使用标签进行工作空间分类和管理
# 推荐标签维度：
# - 环境：production, staging, development
# - 团队：team-platform, team-data, team-security
# - 项目：project-alpha, project-beta
# - 重要性：critical, high, medium, low

# 示例
{
  "tags": [
    "production",
    "team-platform",
    "project-alpha",
    "critical"
  ]
}

6. 监控和日志

1
2
3
4
5
6
7
# 启用日志文件
terraform-mcp-server stdio --log-file /var/log/terraform-mcp.log

# Docker 部署时挂载日志目录
docker run -p 8080:8080 \
  -v /var/log:/var/log \
  hashicorp/terraform-mcp-server streamable-http --log-file /var/log/terraform-mcp.log

7. 高可用部署

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Kubernetes 部署示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: terraform-mcp-server
spec:
  replicas: 3  # 多副本
  selector:
    matchLabels:
      app: terraform-mcp-server
  template:
    metadata:
      labels:
        app: terraform-mcp-server
    spec:
      containers:
      - name: terraform-mcp-server
        image: hashicorp/terraform-mcp-server:0.3.0
        env:
        - name: TRANSPORT_MODE
          value: "streamable-http"
        - name: TRANSPORT_HOST
          value: "0.0.0.0"
        - name: MCP_SESSION_MODE
          value: "stateless"  # 无状态模式
        - name: TFE_TOKEN
          valueFrom:
            secretKeyRef:
              name: terraform-token
              key: token
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: terraform-mcp-server
spec:
  type: LoadBalancer
  ports:
  - port: 8080
    targetPort: 8080
  selector:
    app: terraform-mcp-server

8. 版本管理

1
2
3
4
5
# 固定版本，避免意外升级
docker run hashicorp/terraform-mcp-server:0.3.0  # 推荐

# 避免使用 latest
docker run hashicorp/terraform-mcp-server:latest  # 不推荐

常见问题

Q: 如何获取 TFE Token？

  1. 登录 HCP Terraform
  2. 进入 User Settings → Tokens
  3. 创建新的 API Token
  4. 复制 Token 并配置为 TFE_TOKEN 环境变量

或使用 CLI：

1
2
terraform login
cat ~/.terraform.d/credentials.tfrc.json

Q: Registry 工具和 TFE 工具有什么区别？

  • Registry 工具：访问 Terraform 公共注册表，无需认证，始终可用
  • TFE 工具：访问 HCP Terraform / Terraform Enterprise，需要 TFE_TOKEN

Q: 如何安全地启用破坏性操作？

1
2
3
4
5
6
7
8
9
10
11
# 仅在需要时启用
export ENABLE_TF_OPERATIONS=true

# 启用后可用的工具：
# - delete_workspace_safely
# - action_run (apply/discard/cancel)

# 建议：
# 1. 在生产环境默认禁用
# 2. 仅在维护窗口临时启用
# 3. 操作后立即禁用

Q: Stdio 和 StreamableHTTP 该如何选择？

场景 推荐模式 原因
本地开发 Stdio 简单、快速、无需网络配置
CI/CD Stdio 直接集成，无需额外服务
远程访问 StreamableHTTP 支持网络访问
多用户 StreamableHTTP 共享服务实例
企业部署 StreamableHTTP 集中管理、负载均衡

Q: 如何调试 MCP 连接问题？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 检查服务器健康状态（StreamableHTTP 模式）
curl http://localhost:8080/health

# 2. 启用日志
terraform-mcp-server stdio --log-file /tmp/mcp-debug.log

# 3. 查看日志
tail -f /tmp/mcp-debug.log

# 4. 测试 Docker 容器
docker run -i --rm hashicorp/terraform-mcp-server stdio

# 5. 验证 TFE Token
curl -H "Authorization: Bearer $TFE_TOKEN" \
  https://app.terraform.io/api/v2/organizations

Q: 性能如何优化？

  1. 使用有状态模式（开发环境）- 减少重复认证
  2. 启用速率限制（生产环境）- 防止滥用
  3. 使用无状态模式 + 负载均衡（高负载）- 水平扩展
  4. 缓存常用查询（客户端）- 减少 API 调用
  5. 配置合理的超时（网络）- 避免长时间等待

Q: 支持哪些 Terraform 版本？

服务器本身不执行 Terraform，仅通过 API 与 Terraform Registry 和 HCP Terraform 交互，因此：

  • 兼容所有 Terraform 版本
  • 创建工作空间时可以指定 terraform_version
  • 支持查询所有版本的 Provider 和 Module

Q: 如何迁移现有工作空间？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 使用 MCP 工具实现迁移
# 1. 列出现有工作空间
list_workspaces(organization="old-org")

# 2. 获取工作空间详情
get_workspace_details(organization="old-org", workspace="app")

# 3. 在新组织创建工作空间
create_workspace(organization="new-org", workspace_name="app", ...)

# 4. 复制变量
list_workspace_variables(organization="old-org", workspace="app")
create_workspace_variable(organization="new-org", workspace="app", ...)

# 5. 复制标签
read_workspace_tags(organization="old-org", workspace="app")
create_workspace_tags(organization="new-org", workspace="app", tags=[...])

评分详情

维度 评分 说明
功能性 4.8/5.0 功能全面，涵盖 IaC 全生命周期
文档质量 4.7/5.0 官方文档详细，示例丰富
社区活跃度 4.6/5.0 HashiCorp 官方维护，更新及时
维护状态 4.9/5.0 持续迭代，快速修复问题
代码质量 4.7/5.0 Go 实现，代码规范，测试完善
综合评分 4.7/5.0 顶级的 IaC MCP 实现

总结

Terraform MCP Server 是 HashiCorp 官方提供的顶级 Infrastructure as Code MCP 实现。它将 Terraform 生态的强大能力与 AI 助手完美结合，为 DevOps 和 Platform 团队提供了智能化的基础设施管理方案。

推荐指数: ⭐⭐⭐⭐⭐ (5/5)

适合你的情况：

  • ✅ 使用 Terraform 进行基础设施管理
  • ✅ 需要多云部署能力
  • ✅ 使用 HCP Terraform 或 Terraform Enterprise
  • ✅ 需要策略合规检查
  • ✅ 希望 AI 助手帮助 IaC 开发
  • ✅ 需要工作空间自动化管理

不适合的情况：

  • ❌ 不使用 Terraform
  • ❌ 只需要单一云厂商工具（考虑 AWS MCP、Azure MCP）
  • ❌ 不需要 AI 辅助（直接使用 Terraform CLI）

相关资源

更新时间: 2025-10-14
数据来源: GitHub, 质量评分: 4.7/5.0

© 2026 Generative AI Discovery All Rights Reserved.
Theme by hiero