Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/billing/tools.ts:311-387 (handler)

  The handler function that executes the tool logic: determines the project ID, fetches billing info using Cloud Billing Client's getProjectBillingInfo method, formats the response with details on billing status and account.

  async ({ projectId }) => {
    try {
      // Use project hierarchy: provided -> state manager -> auth default
      const actualProjectId =
        projectId ||
        stateManager.getCurrentProjectId() ||
        (await getProjectId());
  
      if (!actualProjectId) {
        throw new GcpMcpError(
          "No project ID available. Please provide a project ID or configure a default project.",
          "INVALID_ARGUMENT",
          400,
        );
      }
  
      const billingClient = getBillingClient();
  
      logger.debug(`Getting billing info for project: ${actualProjectId}`);
  
      const [billingInfo] = await billingClient.getProjectBillingInfo({
        name: `projects/${actualProjectId}`,
      });
  
      if (!billingInfo) {
        return {
          content: [
            {
              type: "text",
              text: `# Project Billing Information\n\nNo billing information found for project: ${actualProjectId}\n\nThis could mean:\n- The project doesn't exist\n- You don't have billing permissions\n- The project is not associated with a billing account`,
            },
          ],
        };
      }
  
      const projectBillingInfo: ProjectBillingInfo = {
        name: billingInfo.name || "",
        projectId: actualProjectId,
        billingAccountName: billingInfo.billingAccountName || undefined,
        billingEnabled: billingInfo.billingEnabled || false,
      };
  
      let response = `# Project Billing Information\n\n`;
      response += `**Project ID:** ${projectBillingInfo.projectId}\n`;
      response += `**Project Name:** ${projectBillingInfo.name}\n`;
      response += `**Billing Enabled:** ${projectBillingInfo.billingEnabled ? "✅ Yes" : "❌ No"}\n`;
  
      if (projectBillingInfo.billingAccountName) {
        response += `**Billing Account:** ${projectBillingInfo.billingAccountName}\n`;
      } else {
        response += `**Billing Account:** Not associated\n`;
      }
  
      if (!projectBillingInfo.billingEnabled) {
        response += `\n## Required Permissions\n\n`;
        response += `To manage billing for this project, you need:\n`;
        response += `- \`${BILLING_IAM_PERMISSIONS.BILLING_RESOURCE_ASSOCIATIONS_CREATE}\` - To associate with billing account\n`;
        response += `- \`${BILLING_IAM_PERMISSIONS.BILLING_ACCOUNTS_LIST}\` - To list available billing accounts\n`;
      }
  
      return {
        content: [
          {
            type: "text",
            text: response,
          },
        ],
      };
    } catch (error: any) {
      logger.error(`Error getting project billing info: ${error.message}`);
      throw new GcpMcpError(
        `Failed to get project billing info: ${error.message}`,
        error.code || "UNKNOWN",
        error.status || 500,
      );
    }
  },

• src/services/billing/tools.ts:298-309 (schema)

  Input schema for the tool, defining an optional projectId parameter with Zod validation.

  {
    title: "Get Project Billing Information",
    description:
      "Retrieve billing configuration and status for a Google Cloud project",
    inputSchema: {
      projectId: z
        .string()
        .optional()
        .describe(
          "Project ID (defaults to current project from state manager)",
        ),
    },

• src/services/billing/tools.ts:296-388 (registration)

  MCP tool registration call including name, metadata, schema, and inline handler function.

  server.registerTool(
    "gcp-billing-get-project-info",
    {
      title: "Get Project Billing Information",
      description:
        "Retrieve billing configuration and status for a Google Cloud project",
      inputSchema: {
        projectId: z
          .string()
          .optional()
          .describe(
            "Project ID (defaults to current project from state manager)",
          ),
      },
    },
    async ({ projectId }) => {
      try {
        // Use project hierarchy: provided -> state manager -> auth default
        const actualProjectId =
          projectId ||
          stateManager.getCurrentProjectId() ||
          (await getProjectId());
  
        if (!actualProjectId) {
          throw new GcpMcpError(
            "No project ID available. Please provide a project ID or configure a default project.",
            "INVALID_ARGUMENT",
            400,
          );
        }
  
        const billingClient = getBillingClient();
  
        logger.debug(`Getting billing info for project: ${actualProjectId}`);
  
        const [billingInfo] = await billingClient.getProjectBillingInfo({
          name: `projects/${actualProjectId}`,
        });
  
        if (!billingInfo) {
          return {
            content: [
              {
                type: "text",
                text: `# Project Billing Information\n\nNo billing information found for project: ${actualProjectId}\n\nThis could mean:\n- The project doesn't exist\n- You don't have billing permissions\n- The project is not associated with a billing account`,
              },
            ],
          };
        }
  
        const projectBillingInfo: ProjectBillingInfo = {
          name: billingInfo.name || "",
          projectId: actualProjectId,
          billingAccountName: billingInfo.billingAccountName || undefined,
          billingEnabled: billingInfo.billingEnabled || false,
        };
  
        let response = `# Project Billing Information\n\n`;
        response += `**Project ID:** ${projectBillingInfo.projectId}\n`;
        response += `**Project Name:** ${projectBillingInfo.name}\n`;
        response += `**Billing Enabled:** ${projectBillingInfo.billingEnabled ? "✅ Yes" : "❌ No"}\n`;
  
        if (projectBillingInfo.billingAccountName) {
          response += `**Billing Account:** ${projectBillingInfo.billingAccountName}\n`;
        } else {
          response += `**Billing Account:** Not associated\n`;
        }
  
        if (!projectBillingInfo.billingEnabled) {
          response += `\n## Required Permissions\n\n`;
          response += `To manage billing for this project, you need:\n`;
          response += `- \`${BILLING_IAM_PERMISSIONS.BILLING_RESOURCE_ASSOCIATIONS_CREATE}\` - To associate with billing account\n`;
          response += `- \`${BILLING_IAM_PERMISSIONS.BILLING_ACCOUNTS_LIST}\` - To list available billing accounts\n`;
        }
  
        return {
          content: [
            {
              type: "text",
              text: response,
            },
          ],
        };
      } catch (error: any) {
        logger.error(`Error getting project billing info: ${error.message}`);
        throw new GcpMcpError(
          `Failed to get project billing info: ${error.message}`,
          error.code || "UNKNOWN",
          error.status || 500,
        );
      }
    },
  );