list_organizations
Retrieve and filter a paginated list of organizations accessible to the current user, with options to search by name, email, or both, from the terraform-cloud-mcp server.
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 implementing the list_organizations tool. It uses a Pydantic model for parameters, converts to query params, and calls the Terraform Cloud API to list organizations with pagination and filtering.@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 schema model OrganizationListRequest used for input validation and serialization of parameters (page_number, page_size, q, query_email, query_name) for the list_organizations tool.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)Tool registration line where list_organizations from the organizations module is registered as an MCP tool using FastMCP's mcp.tool() decorator.mcp.tool()(organizations.list_organizations)