星战科技xingzhan.cloud
返回市场
terraform云mcp

terraform云mcp

作者：severity118 星标更新：2025-11-02
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

Terraform Cloud MCP 服务器

这是一个集成AI助手与Terraform Cloud API的模型上下文协议（MCP）服务器，允许您通过自然对话管理您的基础设施。该服务器基于Pydantic模型构建，并围绕特定领域的模块进行组织，兼容任何支持MCP的平台，包括Claude、Claude Code CLI、Claude Desktop、Cursor、Copilot Studio等。

版本 Python 类型检查 代码质量

功能

  • 账户管理：获取已认证用户或服务账户的账户详情。
  • 工作区管理：创建、读取、更新、锁定/解锁工作区，并可选删除工作区（带有安全控制）。
  • 项目管理：创建、列出、更新项目，并可选删除项目；管理项目标签绑定并移动工作区到不同项目中。
  • 运行管理：创建运行、列出运行、获取运行详情、应用/丢弃/取消运行。
  • 计划管理：检索计划详情及JSON执行输出，具有高级HTTP重定向处理能力。
  • 应用管理：获取应用详情并从失败状态上传中恢复。
  • 组织管理：列出、创建、更新组织，查看组织权限，并可选删除组织（带有安全控制）。
  • 成本估算：检索详细的基础设施变更成本估算，包括提议的每月成本、先前的成本、资源数量及使用预测。
  • 评估结果：检索健康评估详情、JSON输出、模式文件及日志。
  • 状态版本管理：列出、检索、创建及下载状态版本；获取工作区当前状态。
  • 状态版本输出：列出并检索特定状态版本中的输出，包括值及敏感信息。
  • 变量管理：完成工作区变量及变量集管理，包括创建、更新、分配及可选删除（带有安全控制）。

性能特性

  • 审计安全响应过滤：保守的令牌优化（5-15%减少），100%符合审计要求——保留所有用户责任、安全配置及变更跟踪数据以满足全面合规场景。

安全特性

  • 破坏性操作控制：默认禁用删除操作，需要通过环境变量显式启用。
  • 只读模式：所有写操作可通过设置READ_ONLY_TOOLS=true在生产环境中达到最大安全性。
  • 破坏性提示：MCP客户端会收到潜在危险工具的适当破坏性操作警告。
  • 基于环境的安全性：生产和开发环境可以有不同的安全配置。

快速开始

前提条件

  • Python 3.12+
  • MCP（包括FastMCP和开发工具）
  • uv 包管理器（推荐）或 pip
  • Terraform Cloud API 令牌

创建 Terraform Cloud API 令牌

要使用此MCP服务器，您需要一个Terraform Cloud（或Terraform Enterprise）API令牌：

  1. 登录到HCP Terraform（或您的Terraform Enterprise实例）
  2. 单击右上角的头像并选择用户设置
  3. 导航到左侧边栏的令牌
  4. 单击创建API令牌
  5. 提供描述（例如，“MCP服务器”）
  6. 设置过期日期（出于安全考虑推荐设置）
  7. 单击生成令牌
  8. 立即复制令牌 - 它只会显示一次

在下面的配置步骤中，将此令牌作为TFC_TOKEN环境变量使用。

有关API令牌类型和权限的更多信息，请参阅HCP Terraform API 令牌文档。

环境变量

  • TFC_TOKEN - Terraform Cloud API 令牌（必需）
  • TFC_ADDRESS - Terraform Cloud/Enterprise 地址（可选，默认为 https://app.terraform.io）
  • ENABLE_DELETE_TOOLS - 启用/禁用破坏性操作（可选，默认为 false）
  • READ_ONLY_TOOLS - 启用仅读操作（可选，默认为 false）
  • ENABLE_RAW_RESPONSE - 返回原始而非过滤的响应（可选，默认为 false）

安装

方案 1：本地安装

# 克隆仓库
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装包
uv pip install .

方案 2：Docker 安装

# 克隆仓库
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# 构建 Docker 镜像
docker build -t terraform-cloud-mcp:latest .

添加到 Claude 环境

添加到 Claude Code CLI

# 使用您的Terraform Cloud令牌添加到Claude Code
claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=false -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# 要使用自托管的Terraform Enterprise实例：
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e TFC_ADDRESS=https://terraform.example.com -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# 要启用删除操作（谨慎使用）：
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=true -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

添加到 Claude Desktop

创建一个claude_desktop_config.json配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
本地安装配置：
{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "/path/to/uv", # 通过运行`which uv`获取
      "args": [
        "--directory",
        "/path/to/your/terraform-cloud-mcp", # 此项目的完整路径
        "run",
        "terraform-cloud-mcp"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here", # 替换为实际令牌
        "TFC_ADDRESS": "https://app.terraform.io", # 可选，更改以使用自托管TFE
        "ENABLE_DELETE_TOOLS": "false", # 设置为"true"以启用破坏性操作/工具
        "READ_ONLY_TOOLS": "false" # 设置为"true"以仅启用只读操作/工具
      }
    }
  }
}
Docker 配置：
{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TFC_TOKEN",
        "-e", "TFC_ADDRESS",
        "-e", "ENABLE_DELETE_TOOLS",
        "-e", "READ_ONLY_TOOLS",
        "terraform-cloud-mcp:latest"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here",
        "TFC_ADDRESS": "https://app.terraform.io",
        "ENABLE_DELETE_TOOLS": "false",
        "READ_ONLY_TOOLS": "false"
      }
    }
  }
}

将your_terraform_cloud_token替换为您实际的Terraform Cloud API令牌。

其他 MCP 兼容平台

对于其他平台（如Cursor、Copilot Studio或Glama），请遵循其特定于平台的指令来添加MCP服务器。大多数平台需要：

  1. 服务器路径或启动服务器的命令。
  2. Terraform Cloud API令牌的环境变量（TFC_TOKEN）。
  3. 自托管Terraform Enterprise的可选环境变量（TFC_ADDRESS）。
  4. 启用删除操作的可选环境变量（ENABLE_DELETE_TOOLS=true用于破坏性操作）。
  5. 只读模式的可选环境变量（READ_ONLY_TOOLS=true以禁用所有写操作）。
  6. 需要时自动启动服务器的配置。

可用工具

注意：当READ_ONLY_TOOLS=true时，所有创建、更新、删除、应用及状态修改操作均被禁用。只有读操作（列表、获取、查看）仍然可用。

账户工具

  • get_account_details()：获取已认证用户或服务账户的账户信息。

工作区管理工具

列表 & 搜索

  • list_workspaces(organization, page_number, page_size, search)：列出并筛选工作区。
  • get_workspace_details(workspace_id, organization, workspace_name)：获取特定工作区的详细信息。

创建 & 更新

  • create_workspace(organization, name, params)：使用可选参数创建新的工作区。
  • update_workspace(organization, workspace_name, params)：更新现有工作区的配置。

删除（需ENABLE_DELETE_TOOLS=true）

  • delete_workspace(organization, workspace_name)：删除工作区及其所有内容。
  • safe_delete_workspace(organization, workspace_name)：仅在工作区未管理任何资源时删除。

注意：默认情况下禁用删除操作以确保安全。设置ENABLE_DELETE_TOOLS=true以启用这些破坏性操作。

锁定 & 解锁

  • lock_workspace(workspace_id, reason)：锁定工作区以防止运行。
  • unlock_workspace(workspace_id)：解锁工作区以允许运行。
  • force_unlock_workspace(workspace_id)：强制解锁由其他用户锁定的工作区。

运行管理工具

  • create_run(workspace_id, params)：使用工作区ID创建并排队Terraform运行。
  • list_runs_in_workspace(workspace_id, ...)：使用工作区ID列出并筛选特定工作区中的运行。
  • list_runs_in_organization(organization, ...)：列出并筛选整个组织中的运行。
  • get_run_details(run_id)：获取特定运行的详细信息。
  • apply_run(run_id, comment)：等待确认的应用运行。
  • discard_run(run_id, comment)：等待确认的丢弃运行。
  • cancel_run(run_id, comment)：取消当前正在规划或应用的运行。
  • force_cancel_run(run_id, comment)：立即强制取消运行。
  • force_execute_run(run_id)：通过取消先前的运行强制执行待处理的运行。

计划管理工具

  • get_plan_details(plan_id)：获取特定计划的详细信息。
  • get_plan_json_output(plan_id)：检索特定计划的JSON执行计划，具有适当的重定向处理。
  • get_run_plan_json_output(run_id)：从运行中检索JSON执行计划，具有适当的重定向处理。
  • get_plan_logs(plan_id)：从计划操作中检索日志。

应用管理工具

  • get_apply_details(apply_id)：获取特定应用的详细信息。
  • get_errored_state(apply_id)：从失败的应用中检索错误状态以便恢复。
  • get_apply_logs(apply_id)：从应用操作中检索日志。

项目管理工具

  • create_project(organization, name, params)：使用可选参数创建新的项目。
  • update_project(project_id, params)：更新现有项目的配置。
  • list_projects(organization, ...)：列出并筛选组织中的项目。
  • get_project_details(project_id)：获取特定项目的详细信息。
  • delete_project(project_id)：删除项目（如果包含工作区则失败）。需ENABLE_DELETE_TOOLS=true
  • list_project_tag_bindings(project_id)：列出绑定到项目的标签。
  • add_update_project_tag_bindings(project_id, tag_bindings)：在项目上添加或更新标签绑定。
  • move_workspaces_to_project(project_id, workspace_ids)：将工作区移动到项目中。

组织管理工具

  • get_organization_details(organization)：获取特定组织的详细信息。
  • get_organization_entitlements(organization)：显示组织功能的授权集。
  • list_organizations(page_number, page_size, query, query_email, query_name)：列出并筛选组织。
  • create_organization(name, email, params)：使用可选参数创建新的组织。
  • update_organization(organization, params)：更新现有组织的设置。
  • delete_organization(organization)：删除组织及其所有内容。需ENABLE_DELETE_TOOLS=true

成本估算工具

  • get_cost_estimate_details(cost_estimate_id)：获取特定成本估算的详细信息，包括资源数量（匹配和不匹配）、先前的每月成本、提议的每月成本及月度成本估算的差异。使用运行关系查找特定运行的成本估算ID。

评估结果工具

  • get_assessment_result_details(assessment_result_id)：获取特定健康评估结果的详细信息。
  • get_assessment_json_output(assessment_result_id)：从评估结果中检索JSON执行计划。
  • get_assessment_json_schema(assessment_result_id)：从评估结果中检索JSON模式文件。
  • get_assessment_log_output(assessment_result_id)：从评估结果操作中检索日志。

状态版本管理工具

  • list_state_versions(organization, workspace_name, page_number, page_size, filter_status)：列出并筛选工作区中的状态版本。
  • get_current_state_version(workspace_id)：获取工作区的当前状态版本。
  • get_state_version(state_version_id)：获取特定状态版本的详细信息。
  • create_state_version(workspace_id, serial, md5, params)：在工作区中创建新的状态版本。
  • download_state_file(state_version_id, json_format)：下载原始或JSON格式的状态文件。

状态版本输出工具

  • list_state_version_outputs(state_version_id, page_number, page_size)：列出特定状态版本的输出。
  • get_state_version_output(state_version_output_id)：获取特定状态版本输出的详细信息。

变量管理工具

工作区变量

  • list_workspace_variables(workspace_id)：列出工作区的所有变量（Terraform和环境）。
  • create_workspace_variable(workspace_id, key, category, params)：在工作区中创建新的变量。
  • update_workspace_variable(workspace_id, variable_id, params)：更新现有的工作区变量。
  • delete_workspace_variable(workspace_id, variable_id)：删除工作区变量。需ENABLE_DELETE_TOOLS=true

变量集

  • list_variable_sets(organization, page_number, page_size)：列出组织中的变量集。
  • get_variable_set(varset_id)：获取特定变量集的详细信息。
  • create_variable_set(organization, name, params)：创建新的变量集。
  • update_variable_set(varset_id, params)：更新现有的变量集。
  • delete_variable_set(varset_id)：删除变量集及其所有变量。需ENABLE_DELETE_TOOLS=true
  • assign_variable_set_to_workspaces(varset_id, workspace_ids)：将变量集分配给工作区。
  • unassign_variable_set_from_workspaces(varset_id, workspace_ids)：从工作区移除变量集。
  • assign_variable_set_to_projects(varset_id, project_ids)：将变量集分配给项目。
  • unassign_variable_set_from_projects(varset_id, project_ids)：从项目移除变量集。

变量集变量

  • list_variables_in_variable_set(varset_id)：列出变量集中的所有变量。
  • create_variable_in_variable_set(varset_id, key, category, params)：在变量集中创建变量。
  • update_variable_in_variable_set(varset_id, var_id, params)：更新变量集中的变量。
  • delete_variable_from_variable_set(varset_id, var_id)：从变量集中删除变量。需ENABLE_DELETE_TOOLS=true

注意：变量管理包括Terraform输入变量和环境变量。敏感变量的值会被隐藏以保证安全。默认情况下禁用删除操作，需要ENABLE_DELETE_TOOLS=true。

开发指南

有关详细的开发指导，包括代码标准、Pydantic模式及贡献流程，请参阅我们的开发文档。

快速开发设置

# 克隆仓库
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 以开发模式安装依赖项
uv pip install -e .
uv pip install black mypy pydantic ruff

基本开发命令

# 在开发模式下运行服务器
mcp dev terraform_cloud_mcp/server.py

# 运行测试和质量检查
uv run -m mypy .
uv run -m ruff check .
uv run -m black .

有关代码组织、架构、开发流程及代码质量指南的详细信息，请参阅docs/DEVELOPMENT.md。

文档

代码库包含全面的文档：

  • 代码注释：专注于解释实现决策背后的“为什么”
  • 文档字符串：所有公共函数和类都包含详细的文档字符串
  • 实现参考：开发文档现在引用实际代码示例而不是代码片段
  • 示例文件：docs/目录包含每个领域的详细示例：
    • docs/FILTERING_SYSTEM.md：全面的审计安全响应过滤系统指南（5-15%令牌减少，100%符合审计要求）
    • docs/DEVELOPMENT.md：开发标准和编码指南，附有对实际代码的引用
    • `docs/API_REFERENCES.md