Terraform Partner MCP Server

Terraform MCP服务器+合作伙伴管理资源

Terraform MCP服务器是一个 模型上下文协议（MCP） 服务器，提供与Terraform注册表API的无缝集成，实现高级 基础设施即代码（IaC）开发的自动化和交互能力。

此分支使用合作伙伴管理的资源扩展了基础服务器 -通过AWS security Hub集成和HCP Terraform实现人工智能辅助的安全补救。

新增内容：合作伙伴管理的资源

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    PARTNER-MANAGED RESOURCES WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌──────────────┐                                      ┌──────────────┐         │
│  │ AWS Security │   Discover    ┌──────────────┐       │ HCP Terraform│         │
│  │     Hub      │──────────────▶│   MCP Server │──────▶│  (CLI-Driven │         │
│  │  (Findings)  │               │              │       │   Workspace) │         │
│  └──────────────┘               │  • Sync      │       └──────┬───────┘         │
│                                 │  • Analyze   │              │                  │
│  ┌──────────────┐               │  • Link      │              ▼                  │
│  │    Claude    │◀─────────────▶│  • Remediate │       ┌──────────────┐         │
│  │   Desktop    │   Converse    │              │       │     AWS      │         │
│  │  or CLI      │               └──────────────┘       │  Resources   │         │
│  └──────────────┘                                      │   (Fixed!)   │         │
│                                                        └──────────────┘         │
└─────────────────────────────────────────────────────────────────────────────────┘

关键能力

• 安全发现：自动从AWS安全中心提取调查结果
• 自动ARN→ 地形测绘：发现工作区，解析状态，并将ARN自动链接到Terraform地址
• 自动修复：通过HCP Terraform生成和应用Terraform修复程序
• CLI驱动的工作流：适用于CLI驱动的工作区（通过API上载的配置）

自动资源映射的工作原理

当您提供HCP Terraform组织时，系统 自动发现并链接 资源：

sync_recommendations(terraform_org: "my-org")
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. DISCOVER WORKSPACES                                                   │
│    Lists all workspaces in your org (via HCP Terraform API)             │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. INDEX TERRAFORM STATE                                                 │
│    For each workspace, parses state and extracts cloud resource IDs:    │
│    - ARNs from aws_security_group, aws_instance, aws_s3_bucket, etc.    │
│    - Builds index: ARN → Terraform address                              │
│    Example: "arn:aws:ec2:...:sg-xxx" → "aws_security_group.web"         │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. SYNC & AUTO-LINK                                                      │
│    Fetches findings from Security Hub, matches ARNs to Terraform        │
│    Result: Each finding knows its Terraform resource automatically!     │
└─────────────────────────────────────────────────────────────────────────┘

无需手动链接！ 只需提供 terraform_org 并且系统处理映射。

支持的资源映射

自动发现系统支持以下AWS到Terraform资源映射：

资源如何匹配：系统从Terraform状态中提取云资源ID，并使用ARN将其与安全中心的发现进行匹配。对于每种资源类型，都会检查这些属性（按顺序）：

CLI驱动与VCS驱动的工作区

此扩展专为 CLI驱动的工作区 哪里：

• Terraform配置通过HCP Terraform API直接上传
• 运行是以编程方式触发的（不是通过Git提交）
• AI助手管理配置生命周期

CLI-Driven Workflow (Supported):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Download    │───▶│ Generate    │───▶│ Upload New  │───▶│ Create &    │
│ Current     │    │ Fix Code    │    │ Config      │    │ Apply Run   │
│ Config      │    │             │    │ Version     │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

VCS-Driven Workflow (Experimental - via GitHub PR):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Clone       │───▶│ Generate    │───▶│ Create PR   │───▶│ Merge &     │
│ Repository  │    │ Fix Code    │    │ on GitHub   │    │ Auto-Apply  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

特性

• 双重运输支持：具有可配置端点的Stdio和StreamableHTTP传输
• 地形注册表集成：与提供者、模块和策略的公共Terraform注册表API直接集成
• HCP平台和平台企业支持：完整的工作区管理、组织/项目列表和私有注册表访问
• 工作区操作：创建、更新、删除支持变量、标记和运行管理的工作区
• 合作伙伴管理的资源：安全建议同步、分析和自动修复

安全说明： 在此阶段，MCP服务器仅供本地使用。如果使用StreamableHTTP传输，请始终配置MCP_ALLOWED_ORIGINS环境变量，以限制仅访问受信任的源。

安全说明： 根据查询，MCP服务器可能会向MCP客户端和LLM公开某些Terraform数据。不要将MCP服务器与不受信任的MCP客户端或LLM一起使用。

注意： MCP服务器提供的输出和建议是动态生成的，可能因查询、模型和连接的MCP客户端而异。用户在实施之前应彻底审查所有输出/建议。

快速入门（合作伙伴管理资源）

1.构建服务器

git clone 
cd cc-partner-managed-resources
go build -o terraform-mcp-server ./cmd/terraform-mcp-server

2.配置克劳德桌面

macOS: ~/.config/claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "terraform": {
      "command": "/absolute/path/to/terraform-mcp-server",
      "args": ["--toolsets=partner,terraform"],
      "env": {
        "TFE_TOKEN": "your-hcp-terraform-token",
        "TFE_ADDRESS": "https://app.terraform.io",
        "AWS_ACCESS_KEY_ID": "your-aws-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret-key",
        "AWS_REGION": "us-west-2",
        "ENABLE_TF_OPERATIONS": "true"
      }
    }
  }
}

3.与Claude一起使用

User: "Configure AWS Security Hub for us-west-2"
User: "Sync security recommendations"
User: "Show me HIGH severity findings"
User: "Remediate the SSH security group finding"

可用工具集

合作伙伴工具集-工具参考

配置工具

发现工具

补救工具

资源管理工具

工具工作流序列

合作伙伴工具遵循特定的工作流程顺序：

1. Configure     →  2. Sync         →  3. Review       →  4. Remediate
   ─────────        ──────────         ────────          ─────────────
   configure_aws_   sync_              list_             remediate_
   security_hub     recommendations    recommendations   recommendation
   (or configure_   (with terraform_   get_              (or preview_ +
   aws_             org for auto-      recommendation    apply_
   recommendations) discovery)                           remediation)

笔记：

• sync_recommendations 和 terraform_org 自动发现并链接资源
• 通过手动链接 link_recommendation_resource 仅在自动发现失败时才需要（例如，无法识别的ARN格式）
• 使用 preview_remediation 在应用之前查看更改

环境变量

核心变量

合作伙伴变量

传输变量

测试

E2E测试套件

全面的E2E测试环境可在 test-e2e-remediation/:

cd test-e2e-remediation/scripts

# Configure credentials
cp env.sh.template env.sh
# Edit env.sh with your credentials

# Run MCP CLI test (no Claude Desktop required)
source env.sh
python3 mcp-full-test.py

# Or run the full infrastructure test
./01-setup-workspace.sh
./02-deploy-infrastructure.sh
# ... (see test-e2e-remediation/README.md)

看 test-e2-mediation/README.md 完整的测试文档，包括：

• MCP CLI测试（无克劳德桌面）
• Claude桌面测试，带有逐步提示
• 验证测试结果

示例：安全补救工作流

┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Configure                                                            │
│ > configure_aws_security_hub(region: "us-west-2", categories: ["security"]) │
│ ✓ Configured AWS Security Hub (us-west-2)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 2: Sync with Auto-Discovery                                             │
│ > sync_recommendations(terraform_org: "my-org")  ← Enables auto-linking!    │
│ ✓ Synced 20 findings from AWS Security Hub                                  │
│ ✓ Indexed 5 workspaces with 47 resources                                    │
│ ✓ Auto-linked 3 recommendations to Terraform                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 3: List (already linked!)                                               │
│ > list_recommendations(severity: "high", managed_only: true)                │
│ ✓ [HIGH] EC2.19 - Security group allows SSH from 0.0.0.0/0                  │
│   Resource: sg-096b4ac3e0159bed6                                            │
│   Terraform: aws_security_group.vulnerable  ← Auto-linked!                  │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 4: Remediate (no manual linking needed!)                                │
│ > remediate_recommendation(rec_id, confirm: true)                           │
│ ✓ Run created: run-wQvXTgsbk9MXQd5r                                         │
│ ✓ Status: applied                                                            │
│ ✓ SSH CIDR changed: 0.0.0.0/0 → 10.0.0.0/8                                  │
└─────────────────────────────────────────────────────────────────────────────┘

项目结构

cc-partner-managed-resources/
├── cmd/terraform-mcp-server/     # Main server binary
├── pkg/
│   ├── partner/                  # Partner package
│   │   ├── recommendation_types.go    # Data structures
│   │   ├── recommendation_source.go   # Source interface
│   │   ├── recommendation_registry.go # Session storage
│   │   ├── code_generator.go          # Terraform fix generation
│   │   └── sources/
│   │       └── aws_security_hub.go    # AWS Security Hub source
│   ├── tools/partner/            # MCP tool implementations
│   ├── toolsets/                 # Toolset definitions
│   └── client/                   # Session and client management
├── test-e2e-remediation/         # E2E test environment
│   ├── terraform/                # Vulnerable test infrastructure
│   ├── scripts/                  # Test scripts (CLI + Claude Desktop)
│   └── docs/                     # Test documentation and results
└── README.md                     # This file

代码生成

基于HCL的修改（当前实施）

修复代码生成器(pkg/partner/code_generator.go)用途 HashiCorp hclwrite 图书馆 正确操作HCL AST：

// Parse HCL content
file, diags := hclwrite.ParseConfig([]byte(content), "main.tf", hcl.InitialPos)

// Find and modify resource blocks
resourceBlock := findResourceBlock(body, "aws_security_group", "vulnerable")

// Find nested blocks with criteria matching (e.g., ingress with from_port=22)
for _, block := range body.Blocks() {
    if block.Type() == "ingress" && blockMatchesCriteria(block, {"from_port": "22"}) {
        block.Body().SetAttributeValue("cidr_blocks", cty.ListVal(...))
    }
}

// Output preserves formatting
return string(file.Bytes())

什么效果好：

• 正确的HCL AST解析和序列化
• 嵌套块处理（入口/出口规则、元数据选项、版本配置）
• 选择性块修改（例如，仅SSH入口，而非HTTPS）
• 类型感知属性设置（列表、布尔值、字符串、数字）
• 保留格式和结构
• 如果HCL解析失败，则回退到字符串替换

支持的修复程序：

未来改进

1. 可插拔修复策略

- 将修复模式定义为配置/插件 - 允许每个组织自定义补救规则 - 支持特定于组织的安全策略

1. 试运行验证

- 跑 terraform validate 上传前生成的代码 - 在创建运行之前捕获语法错误

1. 其他推荐来源

- AWS Trusted Advisor（需要业务支持计划） - AWS计算优化器（成本优化-部分实施） - 第三方安全平台

未充分利用的功能

这些功能已实现，但可能不常用：

______________________________________________________________________

原始Terraform MCP服务器文档

先决条件

1. 确保 码头工人 已安装并正在运行，以便在容器化环境中使用服务器。
2. 安装一个支持模型上下文协议（MCP）的AI助手。

命令行选项

# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log] [--toolsets ] [--tools ]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--toolsets ] [--tools ]

说明

MCP服务器的默认说明位于 cmd/terraform-mcp-server/instructions.md，如果这些似乎不适合您组织的Terraform实践，或者如果MCP服务器产生了不准确的响应，请用您自己的说明替换它们，并重建容器或二进制文件。

安装

与Visual Studio代码一起使用

将以下JSON块添加到VS Code中的用户设置（JSON）文件中。您可以按 Ctrl + Shift + P 和打字 Preferences: Open User Settings (JSON).

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

使用Claude Desktop

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

使用Claude代码

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

从源代码安装

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

在本地构建Docker镜像

git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
make docker-build

# 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

可用工具

在此处查看可用工具

工具筛选

控制可用的工具 --toolsets （团体）或 --tools （个人）：

# Enable tool groups
terraform-mcp-server --toolsets=registry,terraform,partner

# Enable specific tools only
terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces

运输支持

1.标准运输（默认）

使用JSON-RPC消息的标准输入/输出通信。非常适合当地发展。

2.可流式HTTP传输

现代基于HTTP的传输支持直接HTTP请求和服务器发送事件（SSE）流。

• 端点: http://{hostname}:8080/mcp
• 健康检查: http://{hostname}:8080/health

发展

先决条件

• 去（检查 go.mod 特定版本的文件）
• Docker（可选，用于容器构建）

可用的生成命令

许可证

此项目根据MPL-2.0开源许可证的条款获得许可。请参考 许可证 提交完整条款的文件。

支持

有关错误报告和功能请求，请在GitHub上打开问题。