list_organizations
Retrieve a paginated list of Terraform Cloud organizations with search filters for name or email to manage access and resources.
Instructions
List organizations with filtering options
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) q: 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.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_number | No | ||
| page_size | No | ||
| q | No | ||
| query_email | No | ||
| query_name | No |
Implementation Reference
- The main handler function that executes the list_organizations tool. It creates a request model, builds query parameters, and calls the Terraform Cloud API GET /organizations endpoint.@handle_api_errors async def list_organizations( page_number: int = 1, page_size: int = 20, q: Optional[str] = None, query_email: Optional[str] = None, query_name: Optional[str] = None, ) -> APIResponse: """List organizations with filtering options 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) q: 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.md for reference documentation """ request = OrganizationListRequest( page_number=page_number, page_size=page_size, q=q, query_email=query_email, query_name=query_name, ) # Get all query parameters - now automatically handles query_email and query_name params = query_params(request) return await api_request("organizations", params=params)
- Pydantic model defining the input schema/validation for the list_organizations tool parameters: page_number, page_size, q, query_email, query_name.class OrganizationListRequest(APIRequest): """Request parameters for listing organizations. These parameters map to the query parameters in the organizations API. The endpoint returns a paginated list of organizations that the authenticated user has access to, along with their details. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations#list-organizations See: docs/models/organization.md for reference """ page_number: Optional[int] = Field(1, ge=1, description="Page number to fetch") page_size: Optional[int] = Field( 20, ge=1, le=100, description="Number of results per page" ) q: Optional[str] = Field( None, description="Search query for name and email", max_length=100 ) query_email: Optional[str] = Field( None, description="Search query for email", max_length=100 ) query_name: Optional[str] = Field( None, description="Search query for name", max_length=100 )
- terraform_cloud_mcp/server.py:77-77 (registration)Registration of the list_organizations tool using FastMCP's mcp.tool() decorator.mcp.tool()(organizations.list_organizations)