terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/variables.py:176-211 (handler)

  The main asynchronous handler function that executes the list_variable_sets tool. It constructs a VariableSetListRequest, generates query parameters, and makes a GET request to the Terraform Cloud API endpoint /organizations/{organization}/varsets.

  @handle_api_errors
  async def list_variable_sets(
      organization: str,
      page_number: int = 1,
      page_size: int = 20,
  ) -> APIResponse:
      """List variable sets in an organization.
  
      Retrieves a paginated list of all variable sets in a Terraform Cloud organization.
      Variable sets allow you to reuse variables across multiple workspaces.
  
      API endpoint: GET /organizations/{organization}/varsets
  
      Args:
          organization: The name of the organization
          page_number: The page number to return (default: 1)
          page_size: The number of items per page (default: 20, max: 100)
  
      Returns:
          Paginated list of variable sets with their configuration and metadata
  
      See:
          docs/tools/variables.md#list-variable-sets for reference documentation
      """
      request = VariableSetListRequest(
          organization=organization,
          page_number=page_number,
          page_size=page_size,
      )
  
      params = query_params(request)
  
      return await api_request(
          f"organizations/{organization}/varsets", method="GET", params=params
      )

• terraform_cloud_mcp/models/variables.py:456-483 (schema)

  Pydantic model defining the input schema and validation for the list_variable_sets tool parameters: organization (required str), page_number (int >=1, default 1), page_size (int 1-100, default 20). Used internally in the handler.

  class VariableSetListRequest(APIRequest):
      """Request model for listing variable sets.
  
      Used for GET /organizations/:organization/varsets endpoint.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/variable-sets
  
      See:
          docs/models/variables.md for reference
      """
  
      organization: str = Field(
          ...,
          description="The organization name",
          min_length=1,
      )
      page_number: int = Field(
          1,
          description="The page number to return",
          ge=1,
      )
      page_size: int = Field(
          20,
          description="The number of items per page",
          ge=1,
          le=100,
      )

• terraform_cloud_mcp/server.py:131-131 (registration)

  Registration of the list_variable_sets tool in the MCP server using FastMCP's mcp.tool() decorator, importing from terraform_cloud_mcp.tools.variables.

  mcp.tool()(variables.list_variable_sets)