nwiizo/tfmcp

分类General
作者Community
星标743
定价Free

简介

tfmcp 是一个基于 MCP 协议的 Terraform 管理服务器，旨在让 AI 助手直接接管基础设施即代码（IaC）的运维工作。它将 Terraform 的核心能力（如读取配置、分析 Plan、执行 Apply 及状态管理）转化为 AI 可调用的工具集。对于开发者而言，这意味着你不再需要频繁在 IDE 和终端之间切换去手动运行命令，而是可以通过自然语言让 AI 帮你检查资源变更或部署环境。该工具上手门槛较低，只要你已有 Terraform 环境，将其接入支持 MCP 的客户端（如 Claude Desktop）即可实现从“对话”到“云资源变更”的闭环。

核心亮点

  • 自然语言驱动 Terraform 配置读取与分析
  • 支持 AI 直接执行 Plan 和 Apply 操作
  • 实时管理和查询 Terraform State 状态
  • 消除手动敲命令，提升 IaC 运维效率

完整文档

tfmcp: Terraform Model Context Protocol 工具

![Trust Score](https://archestra.ai/mcp-catalog/nwiizo__tfmcp)

*⚠️ 本项目包含生产级安全特性，但仍处于积极开发中。虽然安全系统提供了强大的保护，但在生产环境中请仔细审查所有操作。 ⚠️*

tfmcp 是一个命令行工具，旨在帮助您通过 Model Context Protocol (MCP) 与 Terraform 进行交互。它允许 LLM 管理和操作您的 Terraform 环境，包括：

🎮 Demo

查看 tfmcp 在 Claude Desktop 中的实际运行效果：

!tfmcp Demo with Claude Desktop

  • 读取 Terraform 配置文件
  • 分析 Terraform plan 输出
  • 应用 Terraform 配置
  • 管理 Terraform state
  • 创建和修改 Terraform 配置

🎉 当前版本

tfmcp v0.2.2 是当前发布版本：

bash
cargo install tfmcp --version 0.2.2
### v0.2.2 更新内容

  • 支持 RMCP 3.0.1 和 MCP 2026-07-28 discovery
  • 支持带有向后兼容文本内容的结构化 JSON tool 结果
  • 为 tool 和 resource discovery 提供五分钟公共 cache hints
  • 为 MCP 2026-07-28 客户端提供 Sessionless Streamable HTTP 行为
  • Capability 元数据与 tfmcp 实现的方法保持一致

功能特性

| 领域 | 能力 |
| --- | --- |
| Local Terraform | Validate, format, plan/apply 工作流, import 指导, outputs, providers, 依赖图, refresh-only 流程以及受保护的 state 操作 |
| 仓库智能 | Entrypoint/项目检测, 配置分析, 质量检查, 安全检查, 模块健康度, plan 审查以及 drift/state-safety 检查 |
| Registry | 支持具有 HashiCorp 兼容别名的公共/私有 provider, module 和 policy 查询 |
| HCP Terraform / TFE | Organizations, projects, workspaces, runs, plans, applies, variables, policy sets, variable sets, tags, stacks 以及 gated 操作 |
| MCP 部署 | stdio 和 Streamable HTTP, MCP 2026-07-28 discovery, 结构化 tool 结果, cache hints, toolsets, resources, health/metrics, sessions, Host/Origin 验证, rate limits, TLS 配置以及 audit logging |
| 打包 | Cargo, Docker/OCI 元数据, MCP Registry 元数据, Rust Edition 2024 |

安装

从源码安装
bash
# Clone the repository

git clone https://github.com/nwiizo/tfmcp cd tfmcp

Build and install

cargo install --path .
### 来自 Crates.io
bash
cargo install tfmcp
### 使用 Docker
bash
# Clone the repository
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

Build the Docker image

docker build -t tfmcp .

Run the container

docker run -it tfmcp
## 要求
  • Rust 1.88.0+ (Rust Edition 2024)
  • 已安装 Terraform CLI 1.15.8 且已添加到 PATH
  • Claude Desktop (用于 AI assistant 集成)
  • Docker (可选，用于容器化部署)

使用方法
bash
$ tfmcp --help

✨ A CLI tool to manage Terraform configurations and operate Terraform through the Model Context Protocol (MCP).

Usage: tfmcp [OPTIONS] [COMMAND]

Commands:
mcp Launch tfmcp as an MCP server
analyze Analyze Terraform configurations
help Print this message or the help of the given subcommand(s)

Options:
-c, --config <PATH> Path to the configuration file
-d, --dir <PATH> Terraform project directory
-V, --version Print version
-h, --help Print help

### 使用 Docker

当使用 Docker 时，你可以这样运行 tfmcp 命令：

bash
# Run as MCP server (default)
docker run -it tfmcp


Run with specific command and options

docker run -it tfmcp analyze --dir /app/example

Mount your Terraform project directory

docker run -it -v /path/to/your/terraform:/app/terraform tfmcp --dir /app/terraform

Set environment variables

docker run -it -e TFMCP_LOG_LEVEL=debug tfmcp
### 与 Claude Desktop 集成

要在 Claude Desktop 中使用 tfmcp：

1. 如果尚未安装，请安装 tfmcp：

bash
cargo install tfmcp
或者，您可以使用 Docker：
bash
docker build -t tfmcp .
2. 查找已安装的 tfmcp 可执行文件的路径：
bash
which tfmcp
3. 将以下配置添加到 ~/Library/Application\ Support/Claude/claude_desktop_config.json：
json
{
  "mcpServers": {
    "tfmcp": {
      "command": "/path/to/your/tfmcp",  // Replace with the actual path from step 2
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/yourusername",  // Replace with your username
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "TERRAFORM_DIR": "/path/to/your/terraform/project"  // Optional: specify your Terraform project
      }
    }
  }
}
如果你在 Claude Desktop 中使用 Docker，可以按照如下方式进行配置：
json
{
  "mcpServers": {
    "tfmcp": {
      "command": "docker",
      "args": ["run", "--rm", "-v", "/path/to/your/terraform:/app/terraform", "tfmcp", "mcp"],
      "env": {
        "TERRAFORM_DIR": "/app/terraform"
      }
    }
  }
}
4. 重启 Claude Desktop 并启用 tfmcp 工具。

5. 如果 ~/terraform 中不存在项目，tfmcp 将自动创建一个示例 Terraform 项目，以确保 Claude 能立即开始使用 Terraform。该示例项目基于本仓库 example/demo 目录中的示例。

MCP Tools

tfmcp 为 AI 助手提供了 82 个 MCP 工具：### 核心 Terraform 操作
| 工具 | 描述 |
|------|-------------|
| init_terraform | 初始化 Terraform 工作目录 |
| get_terraform_plan | 生成并显示执行计划 |
| analyze_plan | NEW 通过风险评分和建议分析计划 |
| apply_terraform | 应用 Terraform 配置 |
| destroy_terraform | 销毁 Terraform 管理的基础设施 |
| validate_terraform | 验证配置语法 |
| validate_terraform_detailed | 结合指南进行详细验证 |
| get_terraform_state | 显示当前状态 |
| analyze_state | NEW 通过漂移检测分析状态 |
| review_terraform_plan | 审查计划风险、阻碍因素、破坏性变更及建议 |
| summarize_plan_for_pr | 为 PR 评论生成 Markdown 格式的计划摘要 |
| run_terraform_quality_checks | 运行适用于 CI 的验证、模块健康度、指南及 lockfile 检查 |
| inspect_state_safety | 检查状态可读性、漂移风险、lockfile 状态及阻碍因素 |
| detect_drift_candidates | 在不修改基础设施的情况下，从可读状态中检测漂移候选对象 |
| prepare_terraform_change | 生成阻碍因素、警告及建议的变更顺序 |
| list_terraform_resources | 列出所有管理资源 |
| set_terraform_directory | 更改当前项目目录 |### Workspace & State (v0.1.9)
| Tool | Description |
|------|-------------|
| terraform_workspace | NEW 管理 workspaces (list, show, new, select, delete) |
| terraform_import | NEW 导入现有资源 |
| terraform_taint | NEW 标记/取消标记资源为 taint |
| terraform_refresh | NEW 刷新 state |

Code & Output (v0.1.9)

| Tool | Description | |------|-------------| | terraform_fmt | NEW 格式化代码 | | terraform_graph | NEW 生成依赖图 | | terraform_output | NEW 获取 output 值 | | terraform_providers | NEW 通过 lock file 获取 provider 信息 | | check_provider_lockfile | 检查 .terraform.lock.hcl 以确保 provider 选择的可复现性 |

Analysis & Security

| Tool | Description | |------|-------------| | analyze_terraform | 分析配置 | | inspect_terraform_project | 检查本地 Terraform 目录、modules 及可能的入口点 | | detect_terraform_entrypoints | 检测可能的根 module 入口点 | | analyze_module_health | 通过内聚度/耦合度指标分析 module 健康状况 | | get_resource_dependency_graph | 资源依赖关系可视化 | | suggest_module_refactoring | 提供重构建议 | | get_security_status | 进行包含密钥检测的安全扫描 |### Registry | Tool | Description | |------|-------------| | search_providers | 搜索 provider（HashiCorp 兼容别名） | | search_terraform_providers | 搜索 provider | | get_provider_details | Provider 详情（HashiCorp 兼容别名） | | get_provider_info | Provider 详情 | | get_provider_docs | Provider 文档 | | get_provider_capabilities | Provider 资源、数据源、函数和指南 | | search_modules | 搜索 module（HashiCorp 兼容别名） | | search_terraform_modules | 搜索 module | | get_module_details | Module 详情 | | get_latest_module_version | 最新 module 版本 | | get_latest_provider_version | 最新 provider 版本 | | search_policies | 搜索 Sentinel/OPA 策略库 | | get_policy_details | 策略库详情 |### HCP Terraform / Terraform Enterprise (只读) | 工具 | 描述 | |------|-------------| | get_token_permissions | 在不暴露 token 的情况下检查配置的 token 账户详情 | | list_terraform_orgs | 列出可见的 organization | | list_terraform_projects | 列出 organization 中的 project | | list_workspaces | 列出 organization 中的 workspace | | get_workspace_details | 通过 ID 或 organization/name 获取 workspace 详情 | | list_runs | 列出 workspace 的 run | | get_run_details | 获取 run 详情 | | get_plan_details | 获取 plan 详情 | | get_plan_logs | 获取 plan 日志 | | get_plan_json_output | 获取 Terraform JSON plan 输出 | | get_apply_details | 获取 apply 详情 | | get_apply_logs | 获取 apply 日志 | | get_workspace_policy_sets | 获取绑定到 workspace 的 policy set | | list_workspace_variables | 列出 workspace 变量 | | list_variable_sets | 列出 organization 变量集 | | read_workspace_tags | 读取 workspace 标签 | | list_stacks | 列出 Terraform stack | | get_stack_details | 获取 Terraform stack 详情 | | search_private_modules | 搜索私有 registry 模块 | | get_private_module_details | 获取私有 registry 模块详情 | | search_private_providers | 搜索私有 registry provider | | get_private_provider_details | 获取私有 registry provider 详情 |### HCP Terraform / Terraform Enterprise (Gated Operations) | Tool | Description | |------|-------------| | create_workspace | 当 ENABLE_TF_OPERATIONS=true 时创建 workspace | | update_workspace | 当 ENABLE_TF_OPERATIONS=true 时更新 workspace 设置 | | delete_workspace_safely | 当 ENABLE_TF_OPERATIONS=true 时使用安全删除 workspace 操作 | | create_run | 当 ENABLE_TF_OPERATIONS=true 时将 run 加入队列 | | action_run | 当 ENABLE_TF_OPERATIONS=true 时对 run 执行 Apply、discard、cancel、force-cancel 或 force-execute | | create_workspace_variable | 当 ENABLE_TF_OPERATIONS=true 时创建 workspace 变量 | | update_workspace_variable | 当 ENABLE_TF_OPERATIONS=true 时更新 workspace 变量 | | attach_policy_set_to_workspace | 当 ENABLE_TF_OPERATIONS=true 时将 policy set 绑定到 workspace | | create_variable_set | 当 ENABLE_TF_OPERATIONS=true 时创建 variable set | | create_variable_in_variable_set | 当 ENABLE_TF_OPERATIONS=true 时在 variable set 中创建变量 | | delete_variable_in_variable_set | 当 ENABLE_TF_OPERATIONS=true 时从 variable set 中删除变量 | | attach_variable_set_to_workspaces | 当 ENABLE_TF_OPERATIONS=true 时将 variable set 绑定到 workspaces | | detach_variable_set_from_workspaces | 当 ENABLE_TF_OPERATIONS=true 时将 variable set 从 workspaces 解绑 | | create_workspace_tags | 当 ENABLE_TF_OPERATIONS=true 时创建或绑定 workspace 标签 |### MCP Resources | URI | Description | |-----|-------------| | terraform://style-guide / /terraform/style-guide | Terraform 风格指南 | | terraform://module-development / /terraform/module-development | Terraform 模块开发指南 | | terraform://best-practices | tfmcp 安全与运维最佳实践 | | /terraform/providers/{namespace}/name/{name}/version/{version} | HashiCorp 兼容的 provider 文档模板 |

Logs and Troubleshooting

tfmcp server 日志位于：

code
~/Library/Logs/Claude/mcp-server-tfmcp.log
常见问题及解决方案：

环境变量

核心配置

HCP Terraform / Terraform Enterprise

HCP/TFE 写入工具默认禁用，除非设置 ENABLE_TF_OPERATIONS=true，否则将处于关闭状态。default 工具集会隐藏写入工具；请使用 --toolsets operations 或 --toolsets all 来公开这些工具。### MCP Transport
















可流式传输的 HTTP 启动示例：

bash
TRANSPORT_MODE=streamable-http \
TRANSPORT_HOST=127.0.0.1 \
TRANSPORT_PORT=8080 \
tfmcp mcp --toolsets default
MCP endpoint 为 http://127.0.0.1:8080/mcp，health endpoint 为 http://127.0.0.1:8080/health，metrics endpoint 为 http://127.0.0.1:8080/metrics。

Security Considerations

tfmcp 包含专为生产环境设计的全面安全特性：

🔒 Built-in Security Features

🛡️ Security Best Practices

⚙️ Production Configuration
bash
# Recommended production settings

export TFMCP_ALLOW_DANGEROUS_OPS=false # Keep disabled for safety export TFMCP_ALLOW_AUTO_APPROVE=false # Require manual approval export TFMCP_MAX_RESOURCES=10 # Limit resource scope export TFMCP_AUDIT_ENABLED=true # Enable audit logging export TFMCP_AUDIT_LOG_SENSITIVE=false # Don't log sensitive data## Contributing

欢迎贡献！请随时提交 Pull Request。

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
3. 每次 clone 后启用一次由仓库管理的 fast pre-commit 检查：

bash
git config core.hooksPath .githooks
4. 在推送前运行完整的正确性检查：
bash
cargo fmt --all -- --check
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test --locked --all-targets --all-features
5. 提交更改 (git commit -m 'Add some amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 开启 Pull Request

pre-commit hook 始终会检查暂存区的空白字符，并有条件地对受影响的文件运行 cargo fmt、actionlint、Registry 元数据验证、模块耦合度以及重复代码检查。可选的架构工具在 Release.sh 中仍是强制性的；建议安装 cargo-coupling 和 similarity-rs 以在开发期间获得相同的快速反馈。

Release Process

在通过本地发布门禁后，手动执行 Release：

1. 确认 Cargo.toml、Cargo.lock、server.json、Dockerfile、README 和 CHANGELOG.md 使用的目标版本正确。
2. 运行本地发布门禁：./Release.sh v0.2.2。
3. 审查 CHANGELOG.md 和生成的安装包。
4. 提交并推送 main 分支，然后确认该特定 commit 的 CI 已通过。
5. 基于该干净的 commit，使用 ./Release.sh v0.2.2 --publish 进行发布。

Roadmap

以下是 tfmcp 计划的改进和未来功能：

关于 v0.2.1 的合并范围和后续工作，请参阅 docs/releases/v0.2-roadmap.md。发布变更记录在 CHANGELOG.md 中。

Completed

与 Terraform CLI 的核心集成，用于分析和执行操作。 为 AI 助手实现 Model Context Protocol 服务器的初步版本。- [x] 自动项目创建 新增在需要时自动创建 Terraform 示例项目的功能。 支持与 Claude Desktop 的无缝集成。 实现了核心 MCP 方法，包括 tools/list、resources/list、resources/templates/list 和 resources/read。 改进了错误处理和恢复机制，以确保运行的鲁棒性。 新增无需重启服务即可更改当前活动 Terraform 项目目录的能力。 将包发布至 Crates.io，以便通过 Cargo 轻松安装。 新增容器化支持，以简化部署并提高跨平台兼容性。 构建了全面的安全系统，包含可配置的策略、审计日志、访问控制以及生产级安全特性。 采用白盒化 IaC 方法，提供内聚度/耦合度指标、健康评分和重构建议。 可视化资源关系，包括显式和隐式依赖。 支持在 registry 中搜索和探索 Terraform 模块。- [x] 全面测试框架 包含 85+ 个测试，涵盖使用真实 Terraform 配置的集成测试。 迁移至官方 RMCP SDK，并添加正确的 tool annotations 以更好地符合 MCP 规范。 Terraform 代码标准合规性检查，包含 secret 检测和变量质量验证。

进行中

增加对管理多个 Terraform 环境、workspaces 和 modules 的支持。

计划中

实现额外的 MCP 方法和能力，以增强与 AI assistants 的集成。 针对大型 Terraform 项目优化资源占用和响应时间。 集成云供应商 pricing APIs，为 Terraform plans 提供成本估算。 开发基于终端的用户界面，以便于本地使用和调试。 扩展至 Claude 之外，支持其他 AI assistants 和平台。 开发插件架构以允许扩展核心功能。

License

本项目采用 MIT License 许可 - 详情请参阅 LICENSE 文件。

查看官方来源