terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/runs.py:23-100 (handler)

  The main handler function for the 'create_run' tool. It validates input parameters using Pydantic models, constructs the API payload for creating a run in Terraform Cloud, handles relationships and variables, and sends the POST request to the /runs endpoint.
  @handle_api_errors async def create_run( workspace_id: str, params: Optional[RunParams] = None, ) -> APIResponse: """Create a run in a workspace Creates a new Terraform run to trigger infrastructure changes through Terraform Cloud, representing a single execution of plan and apply operations. The run queues in the workspace and executes based on the workspace's execution mode and settings. Use this to deploy new infrastructure, apply configuration changes, or destroy resources. API endpoint: POST /runs Args: workspace_id: The workspace ID to execute the run in (format: "ws-xxxxxxxx") params: Optional run configuration with: - message: Description of the run's purpose - is_destroy: Whether to destroy all resources managed by the workspace - auto_apply: Whether to auto-apply after a successful plan - refresh: Whether to refresh Terraform state before planning - refresh_only: Only refresh the state without planning changes - plan_only: Create a speculative plan without applying - allow_empty_apply: Allow applying when there are no changes - target_addrs: List of resource addresses to specifically target - replace_addrs: List of resource addresses to force replacement - variables: Run-specific variables that override workspace variables - terraform_version: Specific Terraform version to use for this run - save_plan: Save the plan for later execution - debugging_mode: Enable extended debug logging Returns: The created run details with ID, status, configuration information, workspace relationship, and links to associated resources See: docs/tools/run.md for reference documentation """ # Convert optional params to dictionary param_dict = params.model_dump(exclude_none=True) if params else {} # Create validated request object request = RunCreateRequest(workspace_id=workspace_id, **param_dict) # Extract variables for special handling variables = request.variables # Create API payload using utility function payload = create_api_payload( resource_type="runs", model=request, exclude_fields={"workspace_id", "variables"}, # Fields handled separately ) # Add workspace relationship add_relationship( payload=payload, relation_name="workspace", resource_type="workspaces", resource_id=workspace_id, ) # Add optional configuration version relationship if request.configuration_version_id: add_relationship( payload=payload, relation_name="configuration-version", resource_type="configuration-versions", resource_id=request.configuration_version_id, ) # Transform variables to key-value format required by API if variables: payload["data"]["attributes"]["variables"] = [ {"key": var.key, "value": var.value} for var in variables ] return await api_request("runs", method="POST", data=payload)
• terraform_cloud_mcp/server.py:64-64 (registration)

  Registration of the 'create_run' tool in the MCP server using the FastMCP decorator with write permissions configuration.
  mcp.tool(**write_tool_config)(runs.create_run)
• terraform_cloud_mcp/models/runs.py:266-374 (schema)

  Pydantic schemas defining the input parameters for the create_run tool: BaseRunRequest (common fields), RunCreateRequest (full create request), and RunParams (tool input type). Includes enums for operation types, statuses, etc.
  class BaseRunRequest(APIRequest): """Base class for run requests with common fields. Common fields shared across run creation and management APIs. Provides field definitions and validation rules for run operations. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run Note: Consolidates common parameters for consistency across endpoints See: docs/models/run.md for reference """ # Inherits model_config from APIRequest -> BaseModelConfig # Optional fields with their defaults message: Optional[str] = Field(None, description="Message to include with the run") auto_apply: Optional[bool] = Field( None, alias="auto-apply", description="Whether to auto-apply the run when planned (defaults to workspace setting)", ) is_destroy: Optional[bool] = Field( False, alias="is-destroy", description="Whether this run should destroy all resources", ) refresh: Optional[bool] = Field( True, description="Whether to refresh state before plan" ) refresh_only: Optional[bool] = Field( False, alias="refresh-only", description="Whether this is a refresh-only run" ) plan_only: Optional[bool] = Field( False, alias="plan-only", description="Whether this is a speculative, plan-only run", ) allow_empty_apply: Optional[bool] = Field( False, alias="allow-empty-apply", description="Whether to allow apply when there are no changes", ) allow_config_generation: Optional[bool] = Field( False, alias="allow-config-generation", description="Whether to allow generating config for imports", ) target_addrs: Optional[List[str]] = Field( None, alias="target-addrs", description="Resource addresses to target" ) replace_addrs: Optional[List[str]] = Field( None, alias="replace-addrs", description="Resource addresses to replace" ) variables: Optional[List[RunVariable]] = Field( None, description="Run-specific variables" ) terraform_version: Optional[str] = Field( None, alias="terraform-version", description="Specific Terraform version (only valid for plan-only runs)", ) save_plan: Optional[bool] = Field( False, alias="save-plan", description="Whether to save the plan without becoming the current run", ) debugging_mode: Optional[bool] = Field( False, alias="debugging-mode", description="Enable debug logging for this run" ) class RunCreateRequest(BaseRunRequest): """Request model for creating a Terraform Cloud run. Validates and structures the request according to the Terraform Cloud API requirements for creating runs. The model inherits common run attributes from BaseRunRequest and adds workspace_id as a required parameter. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run Note: This inherits all configuration fields from BaseRunRequest and adds workspace_id as a required parameter. This model is typically used internally by the create_run tool function, which accepts parameters directly and constructs the request object. See: docs/models/run.md for reference """ # Required fields workspace_id: str = Field( ..., # No alias needed as field name matches API field name description="The workspace ID to execute the run in (required)", pattern=r"^ws-[a-zA-Z0-9]{16}$", # Standardized workspace ID pattern ) # Optional fields specific to run creation configuration_version_id: Optional[str] = Field( None, alias="configuration-version-id", description="The configuration version ID to use", pattern=r"^cv-[a-zA-Z0-9]{16}$", )