Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/billing/tools.ts:60-128 (handler)

  Handler function that lists GCP billing accounts using the Cloud Billing Client, handles pagination with pageSize/pageToken/filter, formats response with billing account details using formatBillingAccount helper, and returns markdown-formatted text content or error.

  async ({ pageSize, pageToken, filter }) => {
    try {
      const billingClient = getBillingClient();
  
      logger.debug(`Listing billing accounts with pageSize: ${pageSize}`);
  
      const request: any = {
        pageSize,
      };
  
      if (pageToken) {
        request.pageToken = pageToken;
      }
  
      if (filter) {
        request.filter = filter;
      }
  
      const [accounts, nextPageToken] =
        await billingClient.listBillingAccounts(request);
  
      if (!accounts || accounts.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: "No billing accounts found. You may need billing account access permissions.",
            },
          ],
        };
      }
  
      let response = `# Billing Accounts\n\n`;
      response += `Found ${accounts.length} billing account(s):\n\n`;
  
      for (const account of accounts) {
        const billingAccount: BillingAccount = {
          name: account.name || "",
          displayName: account.displayName || "Unknown",
          open: account.open || false,
          masterBillingAccount: account.masterBillingAccount,
          parent: account.parent,
        };
  
        response += formatBillingAccount(billingAccount) + "\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 billing accounts: ${error.message}`);
      throw new GcpMcpError(
        `Failed to list billing accounts: ${error.message}`,
        error.code || "UNKNOWN",
        error.status || 500,
      );
    }
  },

• src/services/billing/tools.ts:39-58 (schema)

  Input schema definition using Zod for the tool parameters: pageSize (1-50, default 20), optional pageToken for pagination, optional filter string.

  {
    title: "List Billing Accounts",
    description:
      "List all Google Cloud billing accounts accessible to the user",
    inputSchema: {
      pageSize: z
        .number()
        .min(1)
        .max(50)
        .default(20)
        .describe("Maximum number of billing accounts to return (1-50)"),
      pageToken: z
        .string()
        .optional()
        .describe("Token for pagination to get next page of results"),
      filter: z
        .string()
        .optional()
        .describe("Optional filter for billing accounts (e.g., 'open=true')"),
    },

• src/services/billing/tools.ts:38-129 (registration)

  MCP server tool registration call including name, schema, and handler reference. This is called from registerBillingTools function.

    "gcp-billing-list-accounts",
    {
      title: "List Billing Accounts",
      description:
        "List all Google Cloud billing accounts accessible to the user",
      inputSchema: {
        pageSize: z
          .number()
          .min(1)
          .max(50)
          .default(20)
          .describe("Maximum number of billing accounts to return (1-50)"),
        pageToken: z
          .string()
          .optional()
          .describe("Token for pagination to get next page of results"),
        filter: z
          .string()
          .optional()
          .describe("Optional filter for billing accounts (e.g., 'open=true')"),
      },
    },
    async ({ pageSize, pageToken, filter }) => {
      try {
        const billingClient = getBillingClient();
  
        logger.debug(`Listing billing accounts with pageSize: ${pageSize}`);
  
        const request: any = {
          pageSize,
        };
  
        if (pageToken) {
          request.pageToken = pageToken;
        }
  
        if (filter) {
          request.filter = filter;
        }
  
        const [accounts, nextPageToken] =
          await billingClient.listBillingAccounts(request);
  
        if (!accounts || accounts.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: "No billing accounts found. You may need billing account access permissions.",
              },
            ],
          };
        }
  
        let response = `# Billing Accounts\n\n`;
        response += `Found ${accounts.length} billing account(s):\n\n`;
  
        for (const account of accounts) {
          const billingAccount: BillingAccount = {
            name: account.name || "",
            displayName: account.displayName || "Unknown",
            open: account.open || false,
            masterBillingAccount: account.masterBillingAccount,
            parent: account.parent,
          };
  
          response += formatBillingAccount(billingAccount) + "\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 billing accounts: ${error.message}`);
        throw new GcpMcpError(
          `Failed to list billing accounts: ${error.message}`,
          error.code || "UNKNOWN",
          error.status || 500,
        );
      }
    },
  );

• src/services/billing/index.ts:13-16 (registration)

  Intermediate registration function for billing service that calls registerBillingTools(server).

  export function registerBillingService(server: McpServer): void {
    registerBillingTools(server);
    registerBillingResources(server);
  }

• src/index.ts:234-234 (registration)

  Top-level call to register the billing service (including gcp-billing-list-accounts tool) in the main MCP server setup.

  registerBillingService(server);