terraform-cloud-mcp

This endpoint shows information about the currently authenticated user or service account, useful for verifying identity, retrieving email address, and checking authentication status. It returns the same type of object as the Users API, but also includes an email address, which is hidden when viewing info about other users. API endpoint: GET /account/details Returns: Raw API response with account information from Terraform Cloud including user ID, username, email address, and authentication status See: docs/tools/account_tools.md for usage examples

Retrieves a paginated list of all workspaces in a Terraform Cloud organization. Results can be filtered using a search string to find specific workspaces by name. Use this tool to discover existing workspaces, check workspace configurations, or find specific workspaces by partial name match. API endpoint: GET /organizations/{organization}/workspaces Args: organization: The name of the organization to list workspaces from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) search: Optional search string to filter workspaces by name Returns: Paginated list of workspaces with their configuration settings and metadata See: docs/tools/workspace_tools.md for usage examples

Retrieves comprehensive information about a workspace including its configuration, VCS settings, execution mode, and other attributes. This is useful for checking workspace settings before operations or determining the current state of a workspace. The workspace can be identified either by its ID directly, or by the combination of organization name and workspace name. API endpoint: - GET /workspaces/{workspace_id} (when using workspace_id) - GET /organizations/{organization}/workspaces/{workspace_name} (when using org+name) Args: workspace_id: The ID of the workspace (format: "ws-xxxxxxxx") organization: The name of the organization (required if workspace_id not provided) workspace_name: The name of the workspace (required if workspace_id not provided) Returns: Comprehensive workspace details including settings, configuration and status See: docs/tools/workspace_tools.md for usage examples

Creates a new Terraform Cloud workspace which serves as an isolated environment for managing infrastructure. Workspaces contain variables, state files, and run histories for a specific infrastructure configuration. API endpoint: POST /organizations/{organization}/workspaces Args: organization: The name of the organization name: The name to give the workspace params: Additional workspace parameters (optional): - description: Human-readable description of the workspace - execution_mode: How Terraform runs are executed (remote, local, agent) - terraform_version: Version of Terraform to use (default: latest) - working_directory: Subdirectory to use when running Terraform - vcs_repo: Version control repository configuration - auto_apply: Whether to automatically apply successful plans - file_triggers_enabled: Whether file changes trigger runs - trigger_prefixes: Directories that trigger runs when changed - trigger_patterns: Glob patterns that trigger runs when files match - allow_destroy_plan: Whether to allow destruction plans - auto_apply_run_trigger: Whether to auto-apply changes from run triggers Returns: The created workspace data including configuration, settings and metadata See: docs/tools/workspace_tools.md for usage examples

Modifies the settings of a Terraform Cloud workspace. This can be used to change attributes like execution mode, VCS repository settings, description, or any other workspace configuration options. Only specified attributes will be updated; unspecified attributes remain unchanged. API endpoint: PATCH /organizations/{organization}/workspaces/{workspace_name} Args: organization: The name of the organization that owns the workspace workspace_name: The name of the workspace to update params: Workspace parameters to update (optional): - name: New name for the workspace (if renaming) - description: Human-readable description of the workspace - execution_mode: How Terraform runs are executed (remote, local, agent) - terraform_version: Version of Terraform to use - working_directory: Subdirectory to use when running Terraform - vcs_repo: Version control repository configuration (oauth-token-id, identifier) - auto_apply: Whether to automatically apply successful plans - file_triggers_enabled: Whether file changes trigger runs - trigger_prefixes: Directories that trigger runs when changed - trigger_patterns: Glob patterns that trigger runs when files match - allow_destroy_plan: Whether to allow destruction plans - auto_apply_run_trigger: Whether to auto-apply changes from run triggers Returns: The updated workspace with all current settings and configuration See: docs/tools/workspace_tools.md for usage examples

Permanently deletes a Terraform Cloud workspace and all its resources including state versions, run history, and configuration versions. This action cannot be undone. WARNING: This is a destructive operation. For workspaces that have active resources, consider running a destroy plan first or use safe_delete_workspace instead. API endpoint: DELETE /organizations/{organization}/workspaces/{workspace_name} Args: organization: The name of the organization that owns the workspace workspace_name: The name of the workspace to delete Returns: Success message with no content (HTTP 204) if successful Error response with explanation if the workspace cannot be deleted See: docs/tools/workspace_tools.md for usage examples

Initiates a safe delete operation which checks if the workspace has resources before deleting it. This is a safer alternative to delete_workspace as it prevents accidental deletion of workspaces with active infrastructure. The operation follows these steps: 1. Checks if the workspace has any resources 2. If no resources exist, deletes the workspace 3. If resources exist, returns an error indicating the workspace cannot be safely deleted API endpoint: POST /organizations/{organization}/workspaces/{workspace_name}/actions/safe-delete Args: organization: The name of the organization that owns the workspace workspace_name: The name of the workspace to delete Returns: Status of the safe delete operation including: - Success response if deletion was completed - Error with details if workspace has resources and cannot be safely deleted - List of resources that would be affected by deletion (if applicable) See: docs/tools/workspace_tools.md for usage examples

Locks a workspace to prevent runs from being queued. This is useful when you want to prevent changes to infrastructure while performing maintenance or making manual adjustments. Locking a workspace does not affect currently running plans or applies. API endpoint: POST /workspaces/{workspace_id}/actions/lock Args: workspace_id: The ID of the workspace to lock (format: "ws-xxxxxxxx") reason: Optional reason for locking Returns: The workspace with updated lock status and related metadata See: docs/tools/workspace_tools.md for usage examples

Removes the lock from a workspace, allowing runs to be queued. This enables normal operation of the workspace after it was previously locked. API endpoint: POST /workspaces/{workspace_id}/actions/unlock Args: workspace_id: The ID of the workspace to unlock (format: "ws-xxxxxxxx") Returns: The workspace with updated lock status and related metadata See: docs/tools/workspace_tools.md for usage examples

Forces a workspace to unlock even when the normal unlock process isn't possible. This is typically needed when a run has orphaned a lock or when the user who locked the workspace is unavailable. This operation requires admin privileges on the workspace. WARNING: Forcing an unlock can be dangerous if the workspace is legitimately locked for active operations. Only use this when you are certain it's safe to unlock. API endpoint: POST /workspaces/{workspace_id}/actions/force-unlock Args: workspace_id: The ID of the workspace to force unlock (format: "ws-xxxxxxxx") Returns: The workspace with updated lock status and related metadata See: docs/tools/workspace_tools.md for usage examples

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_tools.md for usage examples

Retrieves run history for a specific workspace with options to filter by status, operation type, source, and other criteria. Useful for auditing changes, troubleshooting, or monitoring deployment history. API endpoint: GET /workspaces/{workspace_id}/runs Args: workspace_id: The workspace ID to list runs for (format: "ws-xxxxxxxx") page_number: Page number to fetch (default: 1) page_size: Number of results per page (default: 20) filter_operation: Filter by operation type filter_status: Filter by status filter_source: Filter by source filter_status_group: Filter by status group filter_timeframe: Filter by timeframe filter_agent_pool_names: Filter by agent pool names search_user: Search by VCS username search_commit: Search by commit SHA search_basic: Search across run ID, message, commit SHA, and username Returns: List of runs with metadata, status info, and pagination details See: docs/tools/run_tools.md for usage examples

Retrieves run history across all workspaces in an organization with powerful filtering. Useful for organization-wide auditing, monitoring deployments across teams, or finding specific runs by commit or author. API endpoint: GET /organizations/{organization}/runs Args: organization: The organization name page_number: Page number to fetch (default: 1) page_size: Number of results per page (default: 20) filter_operation: Filter by operation type filter_status: Filter by status filter_source: Filter by source filter_status_group: Filter by status group filter_timeframe: Filter by timeframe filter_agent_pool_names: Filter by agent pool names filter_workspace_names: Filter by workspace names search_user: Search by VCS username search_commit: Search by commit SHA search_basic: Basic search across run attributes Returns: List of runs across workspaces with metadata and pagination details See: docs/tools/run_tools.md for usage examples

Retrieves comprehensive information about a run including its current status, plan output, and relationship to other resources. Use to check run progress or results. API endpoint: GET /runs/{run_id} Args: run_id: The ID of the run to retrieve details for (format: "run-xxxxxxxx") Returns: Complete run details including status, plan, and relationships See: docs/tools/run_tools.md for usage examples

Confirms and executes the apply phase for a run that has completed planning and is waiting for approval. Use this when you've reviewed the plan output and want to apply the proposed changes to your infrastructure. API endpoint: POST /runs/{run_id}/actions/apply Args: run_id: The ID of the run to apply (format: "run-xxxxxxxx") comment: An optional comment explaining the reason for applying the run Returns: Run details with updated status information and confirmation of the apply action including timestamp information and any comment provided See: docs/tools/run_tools.md for usage examples

Cancels a run without applying its changes, typically used when the plan shows undesired changes or after reviewing and rejecting a plan. This action removes the run from the queue and unlocks the workspace for new runs. API endpoint: POST /runs/{run_id}/actions/discard Args: run_id: The ID of the run to discard (format: "run-xxxxxxxx") comment: An optional explanation for why the run was discarded Returns: Run status update with discarded state information, timestamp of the discard action, and user information See: docs/tools/run_tools.md for usage examples

Gracefully stops an in-progress run during planning or applying phases. Use this when you need to stop a run that's taking too long, consuming too many resources, or needs to be stopped for any reason. The operation attempts to cleanly terminate the run by sending an interrupt signal. API endpoint: POST /runs/{run_id}/actions/cancel Args: run_id: The ID of the run to cancel (format: "run-xxxxxxxx") comment: An optional explanation for why the run was canceled Returns: Run status update with canceled state, timestamp of cancellation, and any provided comment in the response metadata See: docs/tools/run_tools.md for usage examples

Immediately terminates a run that hasn't responded to a normal cancel request. Use this as a last resort when a run is stuck and not responding to regular cancellation. This action bypasses the graceful shutdown process and forces the workspace to be unlocked. API endpoint: POST /runs/{run_id}/actions/force-cancel Args: run_id: The ID of the run to force cancel (format: "run-xxxxxxxx") comment: An optional explanation for why the run was force canceled Returns: Run status update confirming forced cancellation with timestamp, user information, and workspace unlock status See: docs/tools/run_tools.md for usage examples

Prioritizes a specific run by canceling other queued runs to unlock the workspace, equivalent to clicking "Run this plan now" in the UI. Use this when a run is stuck in the pending queue but needs immediate execution due to urgency or priority over other queued runs. API endpoint: POST /runs/{run_id}/actions/force-execute Args: run_id: The ID of the run to execute (format: "run-xxxxxxxx") Returns: Status update confirming the run has been promoted to active status, with information about which runs were canceled to allow execution See: docs/tools/run_tools.md for usage examples

Retrieves comprehensive information about an organization including settings, email contact info, and configuration defaults. API endpoint: GET /organizations/{organization} Args: organization: The organization name to retrieve details for (required) Returns: Organization details including name, email, settings and configuration See: docs/tools/organization_tools.md for usage examples

Retrieves information about available features and capabilities based on the organization's subscription tier. API endpoint: GET /organizations/{organization}/entitlement-set Args: organization: The organization name to retrieve entitlements for (required) Returns: Entitlement set details including feature limits and subscription information See: docs/tools/organization_tools.md for usage examples

Retrieves a paginated list of organizations the current user has access to, with options to search by name or email address. API endpoint: GET /organizations Args: page_number: Page number to fetch (default: 1) page_size: Number of results per page (default: 20) query: Search query to filter by name and email query_email: Search query to filter by email only query_name: Search query to filter by name only Returns: List of organizations with metadata and pagination information See: docs/tools/organization_tools.md for usage examples

Creates a new organization with the given name and email, allowing workspaces and teams to be created within it. This is the first step in setting up a new environment in Terraform Cloud. API endpoint: POST /organizations Args: name: The name of the organization (required) email: Admin email address (required) params: Additional organization settings: - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources - default_agent_pool_id: Default agent pool ID (required when using agent mode) Returns: The created organization details including ID and created timestamp See: docs/tools/organization_tools.md for usage examples

Modifies organization settings such as email contact, authentication policy, or other configuration options. Only specified attributes will be updated. API endpoint: PATCH /organizations/{organization} Args: organization: The name of the organization to update (required) params: Organization parameters to update: - email: Admin email address for the organization - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources Returns: The updated organization with all current settings See: docs/tools/organization_tools.md for usage examples

Permanently removes an organization including all its workspaces, teams, and resources. This action cannot be undone. Organization names are globally unique and cannot be recreated with the same name later. API endpoint: DELETE /organizations/{organization} Args: organization: The name of the organization to delete (required) Returns: Success confirmation (HTTP 204 No Content) or error details See: docs/tools/organization_tools.md for usage examples