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 creates a new Terraform run in the specified workspace using the Terraform Cloud API, handling parameters, payload construction, relationships, and variables.
  @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 using FastMCP's mcp.tool decorator, with write permissions configuration.
  mcp.tool(**write_tool_config)(runs.create_run)
• terraform_cloud_mcp/models/runs.py:406-423 (schema)

  Pydantic model defining the input parameters (schema) for the create_run tool, including fields like message, is_destroy, auto_apply, variables, etc., inherited from BaseRunRequest.
  class RunParams(BaseRunRequest): """Parameters for run operations without routing fields. This model provides all optional parameters that can be used when creating runs, reusing the field definitions from BaseRunRequest. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run Note: All fields are inherited from BaseRunRequest. See: docs/models/run.md for reference """ # Inherits model_config and all fields from BaseRunRequest
• terraform_cloud_mcp/models/runs.py:340-374 (schema)

  Internal Pydantic model used by the create_run handler for API request validation, extending RunParams with workspace_id and configuration_version_id.
  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}$", )