mcp-server-terraform

mcp-server-terraform

一个 Model Context Protocol（MCP）服务，可让 Claude 通过自然语言管理 Terraform 基础设施。

在 Claude 对话中运行计划、应用更改、检查状态并诊断故障。

功能

无需切换到终端运行 terraform plan，你可以直接询问 Claude：

“规划 /infra/staging 中的更改，并说明会有哪些变化”

“应用更改——但仅限不会销毁任何资源的情况”

“显示 prod 工作区中的所有输出”

“上次应用后出了问题——请诊断原因”

该服务会将这些请求转换为在你机器上实际运行的 terraform CLI 命令，并内置安全确认流程，在执行任何破坏性操作前进行确认。

工具

工具	描述	是否具有破坏性
tf_init	初始化 Terraform 工作目录	否
tf_validate	验证配置语法	否
tf_plan	运行计划并返回差异及风险／成本摘要	否
tf_apply	应用更改（需要 confirmed: true）	是
tf_destroy	销毁基础设施（需要 confirmed: true）	是
tf_output	读取状态中的输出值	否
tf_state	列出、显示、移动或移除状态条目	部分
tf_workspace	列出、显示、选择或创建工作区	否
tf_preflight	运行前检查提供商 CLI 身份验证	否
tf_drift	检测在 Terraform 外部更改的资源	否
tf_resource	导入、标记为 tainted、取消 taint 或刷新资源	是

计划风险与成本摘要

每个计划（以及每次应用预览）都会通过 terraform show -json 进行分析， 并附带结构化摘要——明确标出将被销毁的资源，并标记通常会导致账单骤增的常驻资源，同时估算其月度成本：

── Plan Summary ──
+ 3 create, ~ 1 update, - 0 destroy, ± 0 replace

💸 EXPENSIVE — always-on resources being created:
   ⚠ aws_nat_gateway.main (~$32/month + data processing if left running)
   Remember to tf_destroy when you're done experimenting.

会标记成本的资源类型包括 NAT 网关、负载均衡器、EKS／AKS／GKE 控制平面、RDS／Cloud SQL 实例、ElastiCache、Redshift、MSK 和 Azure Firewall（月费约 900 美元！）。

漂移检测

tf_drift 会运行仅刷新计划，并报告在 Terraform 外部更改的资源（例如在云控制台中手动更改的资源），同时列出发生变化的属性名称和修复选项。

审计日志

将 AUDIT_LOG_PATH 设置为文件路径后，每次工具调用都会以 JSON 行的形式追加记录，其中包含时间戳、工具名称、结果和耗时。变量的值始终会被隐藏（db_password=<redacted>）——日志中只记录名称。

确认流程

tf_apply 和 tf_destroy 使用两步安全流程：

1. 首次调用（不包含 confirmed）→ 运行 terraform plan，显示差异，不执行其他操作
2. 第二次调用（confirmed: true）→ 实际应用更改或销毁资源

系统会指示 Claude，在向你展示计划之前，绝不传入 confirmed: true。

提示词

该服务提供 /tf-diagnose 提示词，引导 Claude 通过系统化的 5 步流程诊断计划或应用失败的问题。

前提条件

• Node.js 18 或更高版本
• PATH 中需包含 Terraform CLI
• Claude Desktop（或任何兼容 MCP 的客户端）

安装

无需安装——直接通过 npm 运行：

npx @rajsir/mcp-server-terraform

或者，如需开发，可从源代码运行：

git clone https://github.com/RajeevSirohi/mcp-server-terraform.git
cd mcp-server-terraform
npm install
npm run build

Claude Desktop 配置

添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "terraform": {
      "command": "npx",
      "args": ["-y", "@rajsir/mcp-server-terraform"]
    }
  }
}

（如果从源代码运行，则使用 "command": "node" 和 "args": ["/absolute/path/to/dist/index.js"]。）

重启 Claude Desktop。你应该会看到一个锤子图标，表示工具已可用。

使用方法

连接后，只需用自然语言与 Claude 讨论你的 Terraform 工作区。以下是一些示例：

在新工作区中首次使用

"在 C:\infra\staging 中初始化 terraform 配置，并检查我是否登录了正确的云账户"

Claude 会运行 tf_init，然后运行 tf_preflight；如果你尚未通过身份验证，它会准确告知你要运行哪个命令（az login、aws configure，……）。

日常的 plan → review → apply 流程

"规划 C:\infra\staging 中的变更，并说明会有哪些变化"

你会看到计划差异以及摘要：创建／更新／销毁的资源数量、明确指出任何破坏性操作，以及针对昂贵常驻资源的成本警告。

"看起来不错，执行 apply"

Claude 会再次显示计划预览并征求你的确认——在你表示同意之前，不会应用任何更改。这道两步确认关卡内置于服务本身，而不只是提示词，因此 Claude 无法跳过它。

检查基础设施

"有没有人在 prod 工作区中直接通过 terraform 之外的方式更改过内容？"

tf_drift 会将状态与实际情况进行比较，并报告在控制台中修改的内容，同时提供接受或还原更改的选项。

"显示所有输出" · "列出状态中的所有内容" · "有哪些工作区？"

学习／实验（例如备考认证）

"在 C:\labs\vpc 中应用 VPC 实验配置，等我说‘完成’后再销毁所有内容"

成本标记在这里很有用——如果实验创建了 NAT 网关或 EKS 集群，计划摘要会提醒你，如果忘记清理，每月会产生多少费用：

💸 EXPENSIVE — always-on resources being created:
   ⚠ aws_nat_gateway.main (~$32/month + data processing if left running)
   Remember to tf_destroy when you're done experimenting.

修复问题

"C:\infra\staging 中的 terraform plan 执行失败了——请诊断问题"

/tf-diagnose 提示词会引导 Claude 按照 validate → providers → plan → state → outputs 的顺序进行系统检查。还有 /tf-login，可按提供商逐步设置身份验证。

"将 S3 存储桶 my-legacy-bucket 导入状态，并命名为 aws_s3_bucket.legacy"

"标记 Web 服务器，使其在下次 apply 时重新创建"

适用于共享或谨慎环境的推荐配置

使用 ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true 运行（参见下方“安全模式”），这样将完全无法使用 apply/destroy；并设置 AUDIT_LOG_PATH，以便记录每项操作。

安全模式

通过环境变量控制可用工具：

变量	效果
ALLOW_ONLY_READONLY_TOOLS=true	仅允许使用 tf_validate、tf_plan、tf_output
ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true	禁用 tf_apply、tf_destroy、tf_state mv/rm
ALLOWED_TOOLS=tf_plan,tf_output	显式指定以逗号分隔的允许列表

示例——只读模式：

{
  "mcpServers": {
    "terraform": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

开发

npm run dev       # watch mode (recompiles on save)
npm test          # run tests
npm run build     # production build

项目结构

src/
  index.ts                  # MCP server entry point, tool registration
  config/                   # (reserved for future config/telemetry)
  models/
    common-parameters.ts    # Shared Zod schemas
  security/
    tf-flags.ts             # Dangerous flag blocking
  tools/
    tf-init.ts
    tf-validate.ts
    tf-plan.ts
    tf-apply.ts             # Two-step confirmation flow
    tf-destroy.ts           # Two-step confirmation flow
    tf-output.ts
    tf-state.ts
    tf-workspace.ts
  utils/
    terraform-runner.ts     # Core exec wrapper, workspace switching
  prompts/
    index.ts                # /tf-diagnose prompt
tests/
  tf-flags.test.ts
  tf-apply.test.ts

添加新工具

1. 创建 src/tools/tf-yourcommand.ts——导出一个 *Schema 常量和一个异步处理函数
2. 在 src/index.ts 中导入两者
3. 将该 schema 添加到 readonlyTools 或 destructiveTools 数组
4. 在 CallToolRequestSchema 处理器的 switch 中添加一个 case

路线图

• 支持 Terraform Cloud / Enterprise API（第 2 阶段）
• OpenTelemetry 跟踪
• 面向远程部署的 SSE / 可流式 HTTP 传输
• 在 GitHub Container Registry 上提供 Docker 镜像
• 计划风险与成本分析
• 漂移检测
• 导入 / taint / untaint / refresh
• 审计日志
• CI（构建、测试矩阵、针对真实 terraform 的端到端测试）

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT——请参阅 LICENSE。