force_unlock_workspace

Force unlock a Terraform Cloud workspace when normal unlocking fails due to orphaned locks or unavailable users. Use with caution for admin-level workspace management.

Instructions

Force unlock a workspace. This should be used with caution.

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.md for reference documentation

Input Schema

TableJSON Schema

Name	Required	Description	Default
`workspace_id`	Yes

Implementation Reference

terraform_cloud_mcp/tools/workspaces.py:297-323 (handler)

The handler function that executes the force_unlock_workspace tool by making a POST request to the Terraform Cloud API endpoint /workspaces/{workspace_id}/actions/force-unlock.

@handle_api_errors
async def force_unlock_workspace(workspace_id: str) -> APIResponse:
    """Force unlock a workspace. This should be used with caution.

    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.md for reference documentation
    """
    # Make API request
    return await api_request(
        f"workspaces/{workspace_id}/actions/force-unlock", method="POST"
    )

terraform_cloud_mcp/server.py:61-61 (registration)
Registration of the force_unlock_workspace tool in the MCP server using the mcp.tool decorator with write_tool_config for non-read-only annotation.
```
mcp.tool(**write_tool_config)(workspaces.force_unlock_workspace)
```

terraform-cloud-mcp