tfmcp: Terraform Model Context Protocol 工具

⚠️ 该项目包含生产就绪的安全特性，但仍在积极开发中。尽管安全系统提供了强大的保护，请在生产环境中仔细审查所有操作。⚠️

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

🎮 演示

使用 Claude Desktop 查看 tfmcp 的实际操作：

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

🎉 最新发布

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

cargo install tfmcp

🆕 v0.1.3 新增功能

• 🔐 全面的安全系统：生产就绪的安全控制，带有审计日志
• 📊 增强的 Terraform 分析：详细的验证和最佳实践建议
• 🛡️ 访问控制：基于文件模式的限制和资源限制
• 📝 审计日志：完整的操作跟踪，用于合规性和监控

功能

• 🚀 Terraform 集成 深度集成到 Terraform CLI 中，以分析和执行操作。

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

• 🔐 企业级安全 生产就绪的安全控制，带有可配置策略、审计日志和访问限制。

• 📊 高级分析 对 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
✨ 一个 CLI 工具，用于管理 Terraform 配置并通过模型上下文协议（MCP）操作 Terraform。

用法：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 集成

要使用 tfmcp 与 Claude Desktop：

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_ALLOW_DANGEROUS_OPS：设置为 true 以启用 apply/destroy 操作（默认：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 包含全面的安全特性，旨在用于生产用途：

🔒 内置安全特性

• 访问控制：自动阻止生产/敏感文件模式
• 操作限制：默认禁用危险操作（apply/destroy）
• 资源限制：可配置的最大资源数保护
• 审计日志：带有时间戳和用户标识的完整操作跟踪
• 目录验证：对项目目录实施安全策略

🛡️ 安全最佳实践

• 默认安全性：默认禁用 apply/destroy 操作 - 只需在必要时明确启用
• 审查计划：始终在应用前审查 Terraform 计划，特别是 AI 生成的计划
• IAM 边界：在云环境中使用适当的 IAM 权限和角色边界
• 审计监控：定期审查审计日志 ~/.tfmcp/audit.log
• 文件模式：内置保护，防止访问 prod*、production* 和 secret* 模式
• Docker 安全：使用容器时，仔细考虑卷挂载和暴露的数据

⚙️ 生产配置

# 推荐的生产设置
export TFMCP_ALLOW_DANGEROUS_OPS=false    # 为了安全，保持禁用
export TFMCP_ALLOW_AUTO_APPROVE=false     # 需要手动批准
export TFMCP_MAX_RESOURCES=10             # 限制资源范围
export TFMCP_AUDIT_ENABLED=true           # 启用审计日志
export TFMCP_AUDIT_LOG_SENSITIVE=false    # 不记录敏感数据

贡献

欢迎贡献！请随时提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m '添加一些惊人的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

发展路线图

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

已完成

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

• MCP 服务器实现 初始实现模型上下文协议服务器，供 AI 助手使用。

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

• Claude Desktop 集成 支持无缝集成到 Claude Desktop。

• 核心 MCP 方法 实现了包括 resources/list 和 prompts/list 在内的基本 MCP 方法。

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

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

• Crates.io 发布 将包发布到 Crates.io，以便通过 Cargo 安装。

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

• 安全增强 包含可配置策略、审计日志、访问控制和生产就绪安全特性的全面安全系统。

正在进行中

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

• 全面的测试框架 扩展测试覆盖率，包括与真实 Terraform 配置的集成测试。

计划中

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

• 扩展的 MCP 协议支持 实现更多的 MCP 方法和能力，以实现与 AI 助手的更丰富集成。

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

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

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

• 与其他 AI 平台集成 扩展支持其他 AI 助手和平台，而不仅仅是 Claude。

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

许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。