/ 目录 / 演练场 / tfmcp
● 社区 nwiizo ⚡ 即开即用

tfmcp

作者 nwiizo · nwiizo/tfmcp

让 Claude 读取你的 Terraform 配置、执行干运行计划,还可以(可选)应用变更 —— 而不用交出你的云凭证。

tfmcp 把本地 Terraform CLI 封装成 MCP server。它读取 HCL、运行 plan/validate/format、探查状态,以及 —— 只有在你明确启用 TFMCP_ALLOW_DANGEROUS_OPS 时 —— 才能执行 apply 或 destroy。凭证保留在你现有的 AWS/GCP/Azure 环境中,tfmcp 永远不会直接接触到它们。

为什么要用

核心特性

实时演示

实际使用效果

tfmcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "tfmcp": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/nwiizo/tfmcp"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "tfmcp": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/nwiizo/tfmcp"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "tfmcp": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/nwiizo/tfmcp"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "tfmcp": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/nwiizo/tfmcp"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "tfmcp",
      "command": "TODO",
      "args": [
        "See README: https://github.com/nwiizo/tfmcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "tfmcp": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/nwiizo/tfmcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add tfmcp -- TODO 'See README: https://github.com/nwiizo/tfmcp'

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: tfmcp

在合并 PR 前审查 Terraform 计划

👤 平台工程师、审查 IaC pull request 的 SRE ⏱ ~10 min intermediate

何时使用: PR 改动了 40+ 个资源,你希望在批准前对影响范围进行健全性检查。

前置条件
  • 安装 Terraform CLI 并配置云凭证 — 运行 aws configure 或等效命令;tfmcp 使用 shell 已有的配置
  • 通过 cargo 安装 tfmcp — cargo install tfmcp
步骤
  1. 指向 Terraform 目录
    将 TERRAFORM_DIR 设置为 ~/work/infra/prod 并运行 terraform plan。总结一下有什么变更。✓ 已复制
    → 干净的计划摘要,包括 add/change/destroy 计数
  2. 要求风险评分明细
    对于每个被销毁或替换的资源,评估风险(低/中/高)并解释原因。标记任何有状态的资源。✓ 已复制
    → 突出显示数据库、队列或数据资源的风险表
  3. 获取 PR 评审备注
    起草 PR 评审备注:批准、请求改动或阻止 —— 并说明理由。✓ 已复制
    → 可实行的评审文本,准备好粘贴

结果: 3 分钟内完成有风险感知的计划审查,而不是 30 分钟,且无需敲击任何 apply 命令。

注意事项
  • 计划在本地成功,但由于 provider 版本不同会在 CI 中失败 — 确保 tfmcp 的 terraform 版本与 CI 中使用的版本一致 —— 通过 .terraform-version 或 tfenv 锁定
  • 状态是远程的,tfmcp 在认证时卡住 — 在调用 tfmcp 前手动运行一次 terraform init 以缓存后端凭证
搭配使用: github · filesystem

检测并解释生产环境中的 Terraform 漂移

👤 审计「Terraform 外部的变更」的 SRE ⏱ ~20 min intermediate

何时使用: 每月漂移检查,或怀疑有云控制台变更时。

步骤
  1. 对 prod 运行计划并查找变更
    对 prod 运行 terraform plan 并告诉我是否有漂移 —— 实际状态与 .tf 不一致的资源。✓ 已复制
    → 漂移资源列表及其差异
  2. 对每个漂移分类
    对于每个漂移,说是否可以安全地 refresh(将 Terraform 与现实协调一致)或需要 re-apply(将现实与 Terraform 协调一致)。✓ 已复制
    → 两个列表:refresh-candidates 和 re-apply-candidates

结果: 一份漂移报告,包含针对每个资源的具体修复计划。

注意事项
  • 对于某些自动伸缩或 provider 管理的字段,漂移是正常的 — 为已知会频繁变化的字段(如 last_modified 时间戳)添加漂移忽略列表(通过 ignore_changes 生命周期块)

理解一个陌生的 Terraform module

👤 新加入的团队成员,被扔进一个 500 个文件的 terraform 仓库 ⏱ ~15 min beginner

何时使用: 你继承了一个基础设施仓库,需要在接触任何东西前了解里面有什么。

步骤
  1. 扫描目录
    列出 ~/work/infra 中的每个 module。对每个 module,告诉我它管理了哪些资源和期望的输入。✓ 已复制
    → module 清单,包含每个 module 的用途和输入
  2. 生成依赖关系图
    运行 terraform graph 并描述 module 依赖树 —— 哪些 module 依赖于哪些。✓ 已复制
    → 清晰的 ASCII 树或编号列表

结果: 脑海中有仓库的地图,无需手工阅读每个 .tf 文件。

注意事项
  • 有些 module 是未使用的死代码 — 要求 tfmcp 标记在根 module 或任何其他 module 中都未被引用的 module
搭配使用: filesystem

组合

与其他 MCP 搭配,撬动十倍杠杆

tfmcp + github

端到端评审 Terraform PR:从 GitHub 拉取差异,通过 tfmcp 在本地运行计划,发布评审备注

从 acme/infra 获取 PR #42,切换到该分支,运行 tfmcp terraform plan,起草评审备注。✓ 已复制
tfmcp + filesystem

批量重构 HCL 文件并验证计划不会改变输出

将 ~/infra 中所有 .tf 文件里的变量 aws_region 重命名为 region,然后确认计划不显示资源变更。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
terraform_plan dir?: str, var_file?: str 安全 —— 在 apply 前总是要运行 1 terraform plan run
terraform_apply dir?: str, auto_approve?: bool 仅当 TFMCP_ALLOW_DANGEROUS_OPS=true 且用户有明确意图时 real cloud changes
terraform_validate dir?: str 提交前 —— 便宜的语法/类型检查 free
terraform_state_list dir?: str 清点 Terraform 知道的资源 free (reads state)
terraform_show dir?: str, resource?: str 查看特定资源的存储状态 free
terraform_graph dir?: str 理解 module/resource 的依赖关系 free

成本与限制

运行它的成本

API 配额
没有 tfmcp 级别的配额;受你的云提供商 API 速率限制
每次调用 Token 数
大型仓库的计划输出可能达到 20k+ tokens —— 使用针对性方法
费用
免费且 MIT 许可;真实成本是 apply 在你的云中触及的任何东西
提示
默认关闭 apply。使用 terraform plan -target=module.x 来限定计划范围并节省上下文 tokens。

安全

权限、密钥、影响范围

最小权限: 本地 terraform 二进制文件 + cloud-provider 读凭证用于 plan/validate
凭据存储: 任何 terraform 已使用的方式 —— AWS 环境变量、~/.aws/credentials、workload identity 等。
数据出站: 直接从你的机器调用你的云提供商 API;tfmcp 不会回调任何地方
切勿授予: 在共享会话中设置 TFMCP_ALLOW_DANGEROUS_OPS=true 当只读凭证足够时,不要使用 admin 云凭证

故障排查

常见错误与修复

未找到 terraform 二进制文件

安装 Terraform 并确保它在 PATH 中。tfmcp 调用 terraform;它不捆绑 terraform。

验证: terraform version
错误:没有有效的凭证来源

你的 shell 的云凭证没有导出。先运行 aws sts get-caller-identity(或等效命令)。

验证: aws sts get-caller-identity
计划说 'apply denied: TFMCP_ALLOW_DANGEROUS_OPS not set'

这是设计如此。如果你真的想 apply,仅为该会话导出 TFMCP_ALLOW_DANGEROUS_OPS=true。

验证: echo $TFMCP_ALLOW_DANGEROUS_OPS
需要初始化后端

在调用 tfmcp 工具前,在目标目录中手动运行一次 terraform init

验证: terraform init

替代方案

tfmcp 对比其他方案

替代方案何时用它替代权衡
terraform-mcp-server (HashiCorp 官方)你想要一个有厂商支持的 MCP 和注册表支持CLI 兼容性较少;state/drift 工具较少
Raw shell MCP + terraform你想要完全的灵活性没有护栏 —— 容易不小心运行 terraform destroy

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills