tfMCP (Nwiizo)

tfmcp：地形模型上下文协议工具


*⚠️ 该项目包括生产就绪的安全功能，但仍在积极开发中。虽然安全系统提供了强大的保护，但请仔细检查生产环境中的所有操作。 ⚠️*

tfmcp是一个命令行工具，可帮助您通过模型上下文协议（MCP）与Terraform交互。它允许LLM管理和操作您的Terraform环境，包括：

🎮 演示

请参阅tfmcp与Claude Desktop的操作：

tfmcp Demo with Claude Desktop

• 读取Terraform配置文件
• 分析地形图输出
• 应用地形配置
• 管理地形状态
• 创建和修改Terraform配置

🎉 最新发布

最新版本的tfmcp（v0.1.9）现已在Crates.io上发布！您可以使用Cargo轻松安装它：

cargo install tfmcp

🆕 v0.1.9的新增功能

• 📊 计划分析：结构化计划分析，包括风险评分和建议
• 🔍 状态分析：带漂移检测的深度状态检查
• 📁 工作空间管理：全地形工作空间支持（列表、显示、新建、选择、删除）
• 📥 导入助手：引导资源导入并生成配置
• ✨ 代码格式化：地形fmt集成
• 🔗 依赖图：带DOT输出的地形图可视化
• 📤 输出管理：地形输出访问
• 🏷️ 油漆/未油漆：资源污染管理（1.5+版本有弃用通知）
• 🔄 状态刷新：显式状态刷新操作
• 📦 提供商信息：具有锁文件解析的详细提供程序信息
• 🦀 防锈版2024：迁移到Rust Edition 2024（需要Rust 1.85.0+）

特性

• 🚀 地形集成

与Terraform CLI深度集成，以分析和执行操作。

• 📄 MCP服务器功能

作为模型上下文协议服务器运行，允许AI助手访问和管理Terraform。

• 🔬 模块健康分析

基于软件工程原理的基础设施即代码的白盒方法，包括内聚/耦合分析、健康评分和重构建议。

• 📊 资源依赖关系图

可视化资源关系，包括显式依赖关系和隐式引用依赖关系。

• 📦 模块注册表集成

从注册表中搜索和探索Terraform模块，获取模块详细信息和版本。

• 🔐 企业安全

具有可配置策略、审核日志和访问限制的生产就绪安全控制。

• 📊 高级分析

详细的Terraform配置分析，包括最佳实践建议和安全检查。

• 📋 指南合规性 （v0.1.8）

Future Architect Terraform指南与合规性评分、秘密检测和可变质量检查的集成。

• ⚡️ 快速燃烧

Rust生态系统通过优化的解析和缓存提供高速处理。

• 🛠️ 自动设置

在需要时自动创建示例Terraform项目，确保即使是新用户也能顺利操作。

• 🐳 Docker支持

在预装了所有依赖项的容器化环境中运行tfmcp。

安装

来自源头

# Clone the repository
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

# Build and install
cargo install --path .

来自Crates.io

cargo install tfmcp

使用Docker

# 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

需求

• 《铁锈》（2021年版）
• Terraform CLI已安装并在PATH中可用
• Claude Desktop（用于AI助手集成）
• Docker（可选，用于容器化部署）

用法

$ 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 to the configuration file
  -d, --dir 
       Terraform project directory
  -V, --version          Print version
  -h, --help             Print help

使用Docker

使用Docker时，可以运行tfmcp命令，如下所示：

# 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：

   cargo install tfmcp

或者，你可以使用Docker：

   docker build -t tfmcp .

1. 找到已安装的tfmcp可执行文件的路径：

   which tfmcp

1. 将以下配置添加到 ~/Library/Application\ Support/Claude/claude_desktop_config.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，你可以这样设置配置：

{
  "mcpServers": {
    "tfmcp": {
      "command": "docker",
      "args": ["run", "--rm", "-v", "/path/to/your/terraform:/app/terraform", "tfmcp", "mcp"],
      "env": {
        "TERRAFORM_DIR": "/app/terraform"
      }
    }
  }
}

1. 重新启动Claude Desktop并启用tfmcp工具。

1. tfmcp将在中自动创建一个示例Terraform项目 ~/terraform 如果没有，确保克劳德可以立即开始使用Terraform。示例项目基于 example/demo 此存储库的目录。

MCP工具

tfmcp为AI助手提供了31个MCP工具：

核心地形操作

工作区和状态（v0.1.9）

代码和输出（v0.1.9）

分析与安全

注册表

日志和故障排除

tfmcp服务器日志可在以下网址获得：

~/Library/Logs/Claude/mcp-server-tfmcp.log

常见问题和解决方案：

• 克劳德无法连接到服务器：确保配置中指向tfmcp可执行文件的路径正确
• 地形项目问题：如果找不到示例Terraform项目，tfmcp会自动创建一个
• 方法未找到错误：MCP协议支持包括资源/列表和提示/列表方法
• Docker问题：如果使用Docker，请确保您的容器具有适当的卷装载和权限

环境变量

核心配置

• TERRAFORM_DIR：设置此选项以指定自定义Terraform项目目录。如果未设置，tfmcp将使用命令行参数、配置文件提供的目录，或回退到 ~/terraform。您还可以在运行时使用以下命令更改项目目录 set_terraform_directory 工具。
• TFMCP_LOG_LEVEL：设置为 debug, info, warn，或 error 以控制日志的冗长程度。
• TFMCP_DEMO_MODE：设置为 true 以启用具有额外安全功能的演示模式。

安全配置

• TFMCP_ALLOW_DANGEROUS_OPS：设置为 true 启用应用/销毁操作（默认值： false)
• TFMCP_ALLOW_AUTO_APPROVE：设置为 true 启用危险操作的自动批准（默认值： false)
• TFMCP_MAX_RESOURCES：设置可以管理的最大资源数（默认值：50）
• TFMCP_AUDIT_ENABLED：设置为 false 禁用审核日志记录（默认值： true)
• TFMCP_AUDIT_LOG_FILE：审核日志文件的自定义路径（默认值： ~/.tfmcp/audit.log)
• TFMCP_AUDIT_LOG_SENSITIVE：设置为 true 在审核日志中包含敏感信息（默认值： false)

安全考虑

tfmcp包括为生产使用而设计的全面安全功能：

🔒 内置安全功能

• 访问控制：自动阻止生产/敏感文件模式
• 操作限制：默认情况下禁用危险操作（应用/销毁）
• 资源限制：可配置的最大资源计数保护
• 审计日志：使用时间戳和用户标识完成操作跟踪
• 目录验证：项目目录的安全策略执行

🛡️ 安全最佳实践

• 默认安全：默认情况下禁用应用/销毁操作-仅在需要时显式启用
• 审查计划：在申请之前，一定要审查Terraform计划，尤其是人工智能生成的计划
• IAM边界：在云环境中使用适当的IAM权限和角色边界
• 审计监控：定期审查审计日志 ~/.tfmcp/audit.log
• 文件模式：内置防访问保护 prod*, production*，以及 secret* 模式
• Docker安全：使用容器时，请仔细考虑卷装载和暴露的数据

⚙️ 生产配置

# 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

贡献

欢迎投稿！请随时提交拉取请求。

1. 克隆该仓库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交前进行质量检查：

   cargo fmt --all
   cargo clippy --all-targets --all-features
   cargo test --all-features

1. 提交您的更改(git commit -m 'Add some amazing feature')
2. 推到分支(git push origin feature/amazing-feature)
3. 打开拉取请求

发布过程

手动完成发布（禁用自动CI发布）：

1. 更新版本 Cargo.toml
2. 创建GitHub版本： gh release create v0.1.x --title "v0.1.x - Title" --notes "Release notes"
3. 发布到crates.io： cargo publish

路线图

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

完成

• \[x\] 基本地形集成\

与Terraform CLI的核心集成，用于分析和执行操作。

• \[x\] MCP服务器实现\

AI助手模型上下文协议服务器的初步实现。

• \[x\] 自动项目创建\

添加了在需要时自动创建示例Terraform项目的功能。

• \[x\] Claude桌面集成\

支持与Claude Desktop无缝集成。

• \[x\] 核心MCP方法\

实施基本的MCP方法，包括资源/列表和提示/列表。

• \[x\] 错误处理改进\

更好的错误处理和恢复机制，实现稳健运行。

• \[x\] 动态项目目录切换\

添加了在不重新启动服务的情况下更改活动Terraform项目目录的功能。

• \[x\] Crates.io出版物\

将软件包发布到Crates.io，以便通过Cargo轻松安装。

• \[x\] Docker支持\

添加了容器化支持，以便于部署和跨平台兼容性。

• \[x\] 增强的安全性

全面的安全系统，具有可配置的策略、审计日志、访问控制和生产就绪的安全功能。

• \[x\] 模块健康分析（v0.1.6）

采用白盒方法处理IaC，包括内聚/耦合度量、健康评分和重构建议。

• \[x\] 资源依赖图（v0.1.6）

资源关系的可视化，包括显式和隐式依赖关系。

• \[x\] 模块注册表集成（v0.1.6）

从注册表中搜索和探索Terraform模块。

• \[x\] 综合测试框架

85多项测试，包括与真实Terraform配置的集成测试。

• \[x\] RMCP SDK迁移（v0.1.8）

迁移到带有适当工具注释的官方RMCP SDK，以提高MCP合规性。

• \[x\] 未来架构师指南（v0.1.8）

通过秘密检测和可变质量验证进行地形编码标准合规性检查。

进行中

• \[ \] 多环境支持

添加对管理多个Terraform环境、工作区和模块的支持。

计划的

• \[ \] 扩展的MCP协议支持

实施额外的MCP方法和功能，以便与AI助手进行更丰富的集成。

• \[ \] 性能优化\

优化大型Terraform项目的资源使用和响应时间。

• \[ \] 成本估算\

与云提供商定价API集成，为Terraform计划提供成本估算。

• \[ \] 交互式TUI\

开发一个基于终端的用户界面，以便于本地使用和调试。

• \[ \] 与其他AI平台集成\

扩展到Claude之外，以支持其他AI助手和平台。

• \[ \] 插件系统\

开发一个插件架构，以允许扩展核心功能。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。