gcp-billing-list-projects

Retrieve all Google Cloud projects linked to a specific billing account to manage costs and track resource usage across your organization.

Instructions

List all projects associated with a specific Google Cloud billing account

Input Schema

TableJSON Schema

Name	Required	Description
`billingAccountName`	Yes	Billing account name (e.g., 'billingAccounts/123456-789ABC-DEF012')
`pageSize`	No	Maximum number of projects to return (1-200)
`pageToken`	No	Token for pagination to get next page of results

Implementation Reference

src/services/billing/tools.ts:223-292 (handler)

The handler function for the 'gcp-billing-list-projects' tool. It uses the Cloud Billing API to list projects associated with a billing account, formats results as a Markdown table with project ID, billing status, and name, supports pagination, and handles errors.

async ({ billingAccountName, pageSize, pageToken }) => {
  try {
    const billingClient = getBillingClient();

    logger.debug(
      `Listing projects for billing account: ${billingAccountName}`,
    );

    const request: any = {
      name: billingAccountName,
      pageSize,
    };

    if (pageToken) {
      request.pageToken = pageToken;
    }

    const [projects, nextPageToken] =
      await billingClient.listProjectBillingInfo(request);

    if (!projects || projects.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No projects found for billing account: ${billingAccountName}`,
          },
        ],
      };
    }

    let response = `# Projects for Billing Account\n\n`;
    response += `**Billing Account:** ${billingAccountName}\n`;
    response += `**Projects Found:** ${projects.length}\n\n`;

    response += "| Project ID | Billing Enabled | Project Name |\n";
    response += "|------------|-----------------|-------------|\n";

    for (const project of projects) {
      const projectId = project.name?.replace("projects/", "") || "Unknown";
      const billingEnabled = project.billingEnabled ? "✅ Yes" : "❌ No";
      const projectName = project.name || "Unknown";

      response += `| ${projectId} | ${billingEnabled} | ${projectName} |\n`;
    }

    if (nextPageToken) {
      response += `\n**Next Page Token:** ${nextPageToken}\n`;
      response += `Use this token with the same tool to get the next page of results.\n`;
    }

    return {
      content: [
        {
          type: "text",
          text: response,
        },
      ],
    };
  } catch (error: any) {
    logger.error(
      `Error listing projects for billing account: ${error.message}`,
    );
    throw new GcpMcpError(
      `Failed to list projects for billing account: ${error.message}`,
      error.code || "UNKNOWN",
      error.status || 500,
    );
  }
},

src/services/billing/tools.ts:201-221 (schema)

Input schema definition for the tool, using Zod for validation of billingAccountName (required), pageSize (1-200, default 50), and optional pageToken.

{
  title: "List Billing Account Projects",
  description:
    "List all projects associated with a specific Google Cloud billing account",
  inputSchema: {
    billingAccountName: z
      .string()
      .describe(
        "Billing account name (e.g., 'billingAccounts/123456-789ABC-DEF012')",
      ),
    pageSize: z
      .number()
      .min(1)
      .max(200)
      .default(50)
      .describe("Maximum number of projects to return (1-200)"),
    pageToken: z
      .string()
      .optional()
      .describe("Token for pagination to get next page of results"),
  },

src/services/billing/tools.ts:199-199 (registration)
Registration of the tool with the MCP server using server.registerTool.
```
server.registerTool(
```

Google Cloud MCP Server