Terraform Cloud MCP 服务器

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

特性

• 账户管理：获取已验证用户或服务账户的账户详情。
• 工作区管理：创建、读取、更新、删除、锁定/解锁工作区。
• 运行管理：创建运行、列出运行、获取运行详情、应用/丢弃/取消运行。
• 组织管理：列出、创建、更新、删除组织，并查看组织权限。
• 未来特性：状态管理、变量管理等更多功能。

快速开始

前提条件

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

安装

# 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 .

添加到 Claude 环境

添加到 Claude Code CLI

# Add to Claude Code with your Terraform Cloud token
claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -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": "my token..." # replace with actual token
      }
    }
  }
}

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

其他支持 MCP 的平台

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

1. 服务器路径或启动服务器的命令。
2. 用于 Terraform Cloud API 令牌的环境变量。
3. 配置以在需要时自动启动服务器。

可用工具

账户工具

• 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): 更新现有工作区的配置。

删除

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

锁定与解锁

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

数据保留

• set_data_retention_policy(workspace_id, days): 设置数据保留策略。
• get_data_retention_policy(workspace_id): 获取当前的数据保留策略。
• delete_data_retention_policy(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_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): 删除一个组织及其所有内容。

开发指南

对于包括代码标准、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/DEVELOPMENT.md：开发标准和编码指南
  • 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 或 pull request。

请参阅我们的贡献指南，了解如何开始、代码质量标准以及 pull request 流程的详细说明。