Terraform Cloud MCP Server

Terraform Cloud MCP 服务

一个模型上下文协议（MCP）服务，可将 AI 助手与 Terraform Cloud API 集成，让你通过自然对话管理基础设施。该服务使用 Pydantic 模型构建，并围绕特定领域的模块组织，兼容所有支持 MCP 的平台，包括 Claude、Claude Code CLI、Claude Desktop、Cursor、Copilot Studio 等。

---

功能

• 账户管理：获取已通过身份验证的用户或服务账户的账户详情。
• 工作区管理：创建、读取、更新、锁定／解锁工作区，并可选择删除工作区（设有安全控制）。
• 项目管理：创建、列出、更新项目，并可选择删除项目；管理项目标签绑定，以及在项目之间移动工作区。
• 运行管理：创建运行、列出运行、获取运行详情、应用／丢弃／取消运行。
• 计划管理：获取计划详情和 JSON 执行输出，并支持高级 HTTP 重定向处理。
• 应用管理：获取应用详情，并从失败的状态上传中恢复。
• 组织管理：列出、创建、更新组织，查看组织权益，并可选择删除组织（设有安全控制）。
• 成本估算：获取基础设施变更的详细成本估算，包括预计月度成本、此前的成本、资源数量和用量预测。
• 评估结果：获取 Terraform Cloud 健康评估的详细信息、JSON 输出、架构文件和日志。
• 状态版本管理：列出、获取、创建和下载状态版本；获取工作区当前状态。
• 状态版本输出：列出并获取状态版本中的特定输出，包括值和敏感性信息。
• 变量管理：全面管理工作区变量和变量集，包括创建、更新、分配，并可选择删除（设有安全控制）。

性能特性

• 审计安全的响应筛选：在 100% 符合审计要求的同时，进行保守的令牌优化（减少 5–15%），为全面合规场景保留所有用户责任追踪、安全配置和变更跟踪数据。

安全特性

• 破坏性操作控制：默认禁用删除操作，需通过环境变量显式启用。
• 只读模式：在生产环境中，为确保最高安全性，可通过 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. 点击右上角的头像，然后选择 User Settings
3. 在左侧边栏中找到 Tokens
4. 点击 Create an API token
5. 填写描述（例如，“MCP Server”）
6. 设置过期日期（出于安全考虑，建议设置）
7. 点击 Generate token
8. 立即复制令牌——它只会显示一次

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

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

环境变量

• 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：本地安装

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install package
uv pip install .

选项 2：Docker 安装

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Build the Docker image
docker build -t terraform-cloud-mcp:latest .

添加到 Claude 环境

添加到 Claude Code CLI

# Add to Claude Code with your Terraform Cloud token
claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=false -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To use a self-hosted Terraform Enterprise instance:
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e TFC_ADDRESS=https://terraform.example.com -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To enable delete operations (use with caution):
# 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 配置文件：

• mac：~/Library/Application Support/Claude/claude_desktop_config.json
• win：%APPDATA%\Claude\claude_desktop_config.json

本地安装配置：

{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "/path/to/uv", # Get this by running: `which uv`
      "args": [
        "--directory",
        "/path/to/your/terraform-cloud-mcp", # Full path to this project
        "run",
        "terraform-cloud-mcp"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here", # replace with actual token
        "TFC_ADDRESS": "https://app.terraform.io", # optional, change for self-hosted TFE
        "ENABLE_DELETE_TOOLS": "false", # set to "true" to enable destructive operations/tools
        "READ_ONLY_TOOLS": "false" # set to  "true" to only enable ready-only operations/tools
      }
    }
  }
}

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, ...)：列出并筛选指定工作区中的运行。
• 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 模式和贡献工作流等详细开发指南，请参阅我们的开发文档。

快速开发环境设置

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with development dependencies
uv pip install -e .
uv pip install black mypy pydantic ruff

基本开发命令

# Run the server in development mode
mcp dev terraform_cloud_mcp/server.py

# Run tests and quality checks
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：Terraform Cloud API 文档链接及实现状态
  • docs/CONTRIBUTING.md：项目贡献指南
  • docs/models/：所有模型类型的参考文档
  • docs/tools/：每个工具的详细参考文档
  • docs/conversations/：使用 API 的示例对话流程

故障排除

1. 检查服务日志（默认启用调试日志）
2. 使用 MCP Inspector（http://localhost:5173）进行调试
3. server.py 中已启用调试日志：

   import logging
   logging.basicConfig(level=logging.DEBUG)
   

---

贡献

欢迎贡献！如果你想为此项目做出贡献，请提交 issue 或拉取请求。

有关入门方法、代码质量标准和拉取请求流程的详细说明，请参阅我们的贡献指南。

免责声明

此项目与 HashiCorp 或 Terraform 无关，也未获得其认可或支持。 “Terraform”和“Terraform Cloud”是 HashiCorp 的商标。 此项目仅在合理使用范围内与 Terraform Cloud 公共 API 交互。