Google Cloud MCP Server

Instructions

Implementation Reference

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

  The core handler function that resolves the project ID from multiple sources, fetches the project billing information using the Cloud Billing API, formats a detailed Markdown response including status and required permissions, and handles errors appropriately.
  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-310 (schema)

  The tool metadata and input schema definition using Zod, specifying an optional projectId parameter with description.
  { 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)

  The MCP server tool registration call that associates the tool name, schema, and 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, ); } }, );
• src/services/billing/types.ts:17-25 (schema)

  TypeScript interface defining the structure of project billing information used in the handler to type the API response.
  /** * Interface for Project Billing Information */ export interface ProjectBillingInfo { name: string; projectId: string; billingAccountName?: string; billingEnabled: boolean; }
• src/services/billing/types.ts:245-249 (helper)

  Helper function that creates and configures the CloudBillingClient instance used by the handler to make API calls.
  export function getBillingClient(): CloudBillingClient { return new CloudBillingClient({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); }