Terraform Cloud MCP

Terraform Cloud MCP服务器

模型上下文协议（MCP）服务器，将人工智能助手与Terraform Cloud API集成在一起，允许您通过自然对话管理基础设施。该服务器采用Pydantic模型构建，围绕特定领域的模块构建，与任何支持MCP的平台兼容，包括Claude、Claude Code CLI、Claude Desktop、Cursor、Copilot Studio等。

______________________________________________________________________

特性

• 账户管理：获取经过身份验证的用户或服务帐户的帐户详细信息。
• 工作空间管理：创建、读取、更新、锁定/解锁工作区，并可选择删除工作区（带安全控制）。
• 项目管理：创建、列出、更新项目，并可选择删除项目；管理项目标签绑定并在项目之间移动工作区。
• 运行管理：创建跑步记录、列出跑步记录、获取跑步记录详细信息、应用/放弃/取消跑步记录。
• 计划管理：使用高级HTTP重定向处理检索计划详细信息和JSON执行输出。
• 应用管理：获取应用程序详细信息并从失败的状态上传中恢复。
• 组织管理：列出、创建、更新组织、查看组织权限，并可选择删除组织（带安全控制）。
• 成本估算：检索基础设施变更的详细成本估算，包括拟议的月度成本、先前成本、资源计数和使用预测。
• 评估结果：从Terraform Cloud健康评估中检索健康评估详细信息、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 Enterprise实例）
2. 点击右上角的头像并选择 用户设置
3. 导航至 代币 在左侧边栏中
4. 点击 创建API令牌
5. 提供描述（例如“MCP服务器”）
6. 设置过期日期（出于安全考虑，建议）
7. 点击 生成令牌
8. 立即复制令牌 -它只会显示一次

使用此令牌作为您的 TFC_TOKEN 以下配置步骤中的环境变量。

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

环境变量

• TFC_TOKEN -Terraform Cloud API令牌（必需）
• TFC_ADDRESS -地形云/企业地址（可选，默认为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代码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桌面

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

• mac:~/库/应用支持/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, ...)：列表和筛选器使用其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)：列出工作区的所有变量（地形和环境）。
• 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.

______________________________________________________________________

文档

代码库包括全面的文档：

• 代码注释：重点解释执行决定背后的“原因”
• 文档字符串：所有公共函数和类都包含详细的文档字符串
• 实施参考：开发文档现在引用实际的代码示例，而不是使用代码片段
• 示例文件：The 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检查器(http://localhost:5173)用于调试
3. 调试日志记录已在中启用 server.py:

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

______________________________________________________________________

贡献

欢迎投稿！如果你想为这个项目做出贡献，请打开一个问题或拉取请求。

查看我们的 贡献指南 有关如何开始、代码质量标准和pull请求过程的详细说明。

免责声明

本项目与HashiCorp或Terraform没有附属关系、关联或认可。 “Terraform”和“Terraform Cloud”是HashiCorp的商标。 该项目仅与公平使用的TerraformCloud公共API进行交互。