tfmcp：Terraform模型上下文协议工具

⚠️ 本项目处于实验阶段，功能可能随时变更。请谨慎使用！⚠️

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

🎮 演示

观看Claude Desktop中使用tfmcp的效果：

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

🎉 最新发布

tfmcp的第一个稳定版本（v0.1.1）现已在Crates.io上发布！您可以使用Cargo轻松安装：

cargo install tfmcp

功能特点

• 🚀 Terraform集成
  与Terraform CLI深度集成，用于分析和执行操作。

• 📄 MCP服务器功能
  作为Model Context Protocol服务器运行，允许AI助手访问和管理Terraform。

• ⚡️ 极速处理
  基于Rust生态系统的高性能处理。

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

• 🐳 Docker支持
  在容器化环境中运行tfmcp，所有依赖项都已预装。

安装

从源码安装

# 克隆仓库
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

# 构建并安装
cargo install --path .

从Crates.io安装

cargo install tfmcp

使用Docker

# 克隆仓库
git clone https://github.com/nwiizo/tfmcp
cd tfmcp

# 构建Docker镜像
docker build -t tfmcp .

# 运行容器
docker run -it tfmcp

系统要求

• Rust（2021版）
• 已安装且PATH中可用的Terraform CLI
• Claude Desktop（用于AI助手集成）
• Docker（可选，用于容器化部署）

使用方法

$ tfmcp --help
✨ 一个通过Model Context Protocol（MCP）管理Terraform配置和操作Terraform的CLI工具。

用法：tfmcp [选项] [命令]

命令：
  mcp       将tfmcp作为MCP服务器启动
  analyze   分析Terraform配置
  help      打印此消息或给定子命令的帮助信息

选项：
  -c, --config <路径>    配置文件路径
  -d, --dir <路径>       Terraform项目目录
  -V, --version          打印版本
  -h, --help             打印帮助

使用Docker

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

# 作为MCP服务器运行（默认）
docker run -it tfmcp

# 运行特定命令和选项
docker run -it tfmcp analyze --dir /app/example

# 挂载您的Terraform项目目录
docker run -it -v /path/to/your/terraform:/app/terraform tfmcp --dir /app/terraform

# 设置环境变量
docker run -it -e TFMCP_LOG_LEVEL=debug tfmcp

与Claude Desktop集成

要在Claude Desktop中使用tfmcp：

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

   cargo install tfmcp
   

   或者，您也可以使用Docker：

   docker build -t tfmcp .
   

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

   which tfmcp
   

3. 将以下配置添加到~/Library/Application\ Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tfmcp": {
      "command": "/path/to/your/tfmcp",  // 替换为步骤2中的实际路径
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/yourusername",  // 替换为您的用户名
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "TERRAFORM_DIR": "/path/to/your/terraform/project"  // 可选：指定您的Terraform项目
      }
    }
  }
}

如果您使用Docker与Claude Desktop配合使用，可以这样设置配置：

{
  "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. 如果不存在，tfmcp会自动在~/terraform中创建一个示例Terraform项目，确保Claude可以立即开始使用Terraform。该示例项目基于本仓库example/demo目录中包含的示例。

日志和故障排除

tfmcp服务器日志位于：

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

常见问题及解决方案：

• Claude无法连接到服务器：确保配置中的tfmcp可执行文件路径正确
• Terraform项目问题：如果未找到项目，tfmcp会自动创建一个示例Terraform项目
• 方法未找到错误：MCP协议支持包括resources/list和prompts/list等方法
• Docker问题：如果使用Docker，请确保容器有正确的卷挂载和权限

环境变量

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

安全注意事项

使用tfmcp时，请注意以下安全事项：

• tfmcp代表您执行Terraform命令，这可能会创建、修改或销毁基础设施
• 在生产环境中，请考虑使用适当的IAM权限和角色边界
• 在应用之前，请仔细检查所有Terraform计划，特别是由AI生成的计划
• 您的Terraform状态中的敏感信息可能对AI助手可见
• 使用Docker时，请小心挂载可能暴露敏感数据的卷

贡献

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

1. 叉取仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

路线图

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

已完成

• [x] 基本Terraform集成
  与Terraform CLI的核心集成，用于分析和执行操作。

• [x] MCP服务器实现
  为AI助手实现的Model Context Protocol服务器的初始版本。

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

• [x] Claude Desktop集成
  支持与Claude Desktop的无缝集成。

• [x] 核心MCP方法
  实现了包括resources/list和prompts/list等关键MCP方法。

• [x] 错误处理改进
  更好的错误处理和恢复机制，以实现稳健的操作。

• [x] 动态项目目录切换
  添加了无需重启服务即可更改活动Terraform项目目录的能力。

• [x] Crates.io发布
  将包发布到Crates.io，以便通过Cargo轻松安装。

• [x] Docker支持
  添加了容器化支持，便于部署和跨平台兼容性。

进行中

• [ ] 增强的Terraform分析
  实现对Terraform配置、计划和状态文件的更深入解析和分析。

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

• [ ] 安全增强
  改进安全功能，包括更好的身份验证和授权机制。

• [ ] 扩展的MCP协议支持
  实现额外的MCP方法和功能，以实现与AI助手的更丰富集成。

• [ ] 交互式TUI
  开发基于终端的用户界面，便于本地使用和调试。

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

• [ ] 性能优化
  优化资源使用和响应时间，适用于大型Terraform项目。

• [ ] 与其他AI平台的集成
  扩展到Claude之外，支持其他AI助手和平台。

• [ ] 全面的测试框架
  扩大测试覆盖范围，包括与真实Terraform配置的集成测试。

• [ ] 插件系统
  开发插件架构，以允许扩展核心功能。

许可证

本项目根据MIT许可证授权 - 详情请参阅LICENSE文件。