terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/organizations.py:69-108 (handler)

  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)

• terraform_cloud_mcp/models/organizations.py:84-110 (schema)

  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)