Hcp Terraform MCP

HCP Terraform MCP服务器


一种模型上下文协议（MCP）服务器，为AI代理提供对HCP Terraform API的标准化访问，用于管理项目、工作区和运行。

项目状态-第3阶段完成✅

所有三个实施阶段都已完成，为HCP Terraform管理提供了一个功能齐全的MCP服务器。

已完成的功能

第一阶段-基础：

• 使用uv包管理器初始化Python项目
• MCP Python SDK和HTTP客户端依赖关系
• 开发环境和测试框架设置
• 带认证的HCP Terraform API客户端
• 速率限制（30个请求/秒合规）
• JSON API响应解析和错误处理
• 带健康检查工具的基本MCP服务器结构
• 通过环境变量进行配置管理
• 基本测试套件

第2阶段——核心运营：

• 项目管理（CRUD操作）
• 工作区管理（创建、更新、锁定/解锁）
• 运行管理（创建、应用、取消运行）
• 完整的API客户端实现
• 全面的错误处理和验证

第3阶段-高级功能：

• 具有动态发现功能的增强资源处理程序
• 5分钟TTL缓存以优化性能
• 4个全面的提示模板
• 带有明确错误消息的环境验证
• API响应验证的冗余模型
• MCP格式兼容性修复
• MCP检查器兼容性
• 综合测试套件（19项测试通过）

项目结构

hcp-terraform-mcp/
  src/hcp_terraform_mcp/
    __init__.py
    __main__.py               # Main entry point
    server.py                 # MCP server implementation (165 lines)
    client.py                 # HCP Terraform API client (392 lines)
    config.py                 # Configuration management (48 lines)
    models.py                 # Pydantic models for API responses (161 lines)
    tool_definitions.py       # Tool definitions (313 lines)
    tool_handlers.py          # Tool implementation handlers (200 lines)
    resource_handlers.py      # Resource discovery handlers (110 lines)
  tests/
    test_client.py            # Client tests (14 tests)
    test_server.py            # Server tests (5 tests)
  .env.example              # Environment variables template
  pytest.ini                # Test configuration
  project-plan.md           # Implementation plan
  pyproject.toml            # Project dependencies
  CLAUDE.md                 # Claude Code guidance

设置

1. 安装依赖项：

   uv sync

1. 配置环境：

   cp .env.example .env
   # Edit .env with your HCP Terraform credentials

1. 运行测试：

   uv run pytest

1. 运行MCP服务器：

   uv run python -m hcp_terraform_mcp

1. 使用MCP检查器运行（用于调试/测试）：

   # Install MCP Inspector
   npx @modelcontextprotocol/inspector uv run python -m hcp_terraform_mcp

这将启动MCP Inspector web界面，允许您：

- 检查可用的工具、资源和提示 - 交互式测试工具调用 - 调试MCP服务器响应 - 查看服务器日志和性能指标

配置

在您的 .env 文件：

• TFC_API_TOKEN：您的HCP Terraform API令牌（必需）
• TFC_ORGANIZATION：您的组织名称（必填）
• TFC_BASE_URL：API基本URL（默认值：https://app.terraform.io/api/v2)
• TFC_ENABLE_CACHING：启用5分钟响应缓存（默认值：true）
• TFC_DEBUG_MODE：启用调试日志记录（默认值：false）

当前MCP能力

工具（共14个）

健康与连接：

• health_check -检查HCP Terraform API连接

项目管理：

• create_project -创建新的HCP Terraform项目
• list_projects -列出组织中的所有项目
• delete_project -按ID删除项目

工作区管理：

• create_workspace -创建新工作区
• list_workspaces -列出工作区（带可选项目筛选）
• update_workspace -更新工作区设置
• lock_workspace -锁定工作区以防止更改
• unlock_workspace -解锁工作区

运行管理：

• create_run -创建并执行新运行
• list_runs -工作区的列表运行
• get_run -获取特定跑步的详细信息
• apply_run -应用计划运行
• cancel_run -取消正在运行的操作

资源

• terraform://organization/info -组织详细信息和元数据
• terraform://projects/ -动态发现所有项目
• terraform://workspaces/ -动态发现所有工作区
• terraform://runs/ -动态发现最近的跑步记录

提示（4个综合模板）

• terraform_status -组织和基础设施状态概述
• terraform_deployment -部署规划和执行指导
• workspace_setup -工作空间配置和管理
• run_monitoring -运行执行监控和故障排除

添加到克劳德代码

在本地设置MCP服务器后，您可以将其添加到Claude Code中：

先决条件

1. 安装MCP服务器：

   # From the project directory
   uv sync
   uv pip install -e .

1. 设置环境变量：

   cp .env.example .env
   # Edit .env with your HCP Terraform credentials:
   # TFC_API_TOKEN=your_terraform_cloud_api_token_here
   # TFC_ORGANIZATION=your_organization_name
   # TFC_BASE_URL=https://app.terraform.io/api/v2

将服务器添加到Claude代码

选项1：项目特定配置

将服务器添加到当前项目中：

claude mcp add hcp-terraform \
  -e TFC_API_TOKEN=your_token_here \
  -e TFC_ORGANIZATION=your_org_name \
  -e TFC_BASE_URL=https://app.terraform.io/api/v2 \
  -- uv run hcp-terraform-mcp

选项2：用户范围配置

为所有Claude Code会话添加服务器：

claude mcp add hcp-terraform \
  --scope user \
  -e TFC_API_TOKEN=your_token_here \
  -e TFC_ORGANIZATION=your_org_name \
  -e TFC_BASE_URL=https://app.terraform.io/api/v2 \
  -- uv run hcp-terraform-mcp

选项3：使用环境文件

如果您更喜欢使用 .env 文件：

# First, ensure your .env file is properly configured
claude mcp add hcp-terraform \
  -- bash -c "source .env && uv run hcp-terraform-mcp"

验证安装

检查服务器是否配置正确：

# List all MCP servers
claude mcp list

# Get details about the HCP Terraform server
claude mcp get hcp-terraform

Claude代码中的用法

添加后，您可以在Claude Code中使用服务器的全面功能：

项目管理：

• 创建、列出和删除项目
• 在项目中组织工作空间

工作区操作：

• 创建和配置工作区
• 更新工作区设置和变量
• 锁定/解锁工作区以进行维护

基础设施部署：

• 创建和执行运行
• 监控运行进度和日志
• 应用计划更改
• 取消正在运行的操作

资源发现：

• 浏览所有项目、工作区和运行
• 获取有关基础设施状态的详细信息

指导工作流程：

• 在常见场景中使用提示模板
• 获得部署规划方面的帮助
• 监控基础设施健康状况

故障排除

服务器未启动：

• 验证您的API令牌是否具有正确的权限
• 检查组织名称拼写是否正确
• 确保服务器已安装： uv pip install -e .

权限错误：

• 您的API令牌需要对组织进行读取访问
• 对于写入操作（在未来阶段），您需要适当的工作区权限

连接问题：

• 验证 TFC_BASE_URL 适用于您的HCP Terraform实例
• 检查HCP Terraform的网络连接

删除服务器

如果需要删除服务器：

claude mcp remove hcp-terraform

下一个开发阶段

第4阶段（未来）-API资源管理器集成：

• 高级分析和查询功能
• 全组织数据探索
• 基础设施审计和合规工具
• 自定义报告和指标

看 implementation-plan.md 完整的发展路线图。

技术规格

• 语言：Python 3.11+
• 框架：MCP（模型上下文协议）Python SDK
• API客户端：具有速率限制的HTTP客户端（30请求/秒）
• 缓存：5分钟TTL用于性能优化
• 测试：19项综合测试，模拟API响应
• 代码质量：全程键入提示、错误处理和日志记录