Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/billing/tools.ts:681-780 (handler)

  The core handler function for the 'gcp-billing-analyse-costs' tool. It uses mock data to simulate cost analysis, computes percentage changes for trends, formats the output as Markdown, and returns structured content. Note that this is a mock implementation requiring BigQuery export for real data.
  async ({ billingAccountName, startDate, endDate, projectId, serviceId, groupBy, }) => { try { logger.debug( `Analysing costs for billing account: ${billingAccountName}`, ); // Use project hierarchy: provided -> state manager -> auth default const actualProjectId = projectId || stateManager.getCurrentProjectId() || (await getProjectId()); // Note: This is a mock implementation since BigQuery billing export or // Cloud Billing Report API would be needed for actual cost data const mockCostData: CostData[] = [ { billingAccountName, projectId: actualProjectId || "example-project-1", serviceId: serviceId || "compute.googleapis.com", cost: { amount: 1250.5, currency: "USD" }, usage: { amount: 100, unit: "hours" }, period: { startTime: startDate, endTime: endDate }, labels: { environment: "production" }, }, { billingAccountName, projectId: actualProjectId || "example-project-2", serviceId: serviceId || "storage.googleapis.com", cost: { amount: 89.25, currency: "USD" }, usage: { amount: 500, unit: "GB" }, period: { startTime: startDate, endTime: endDate }, labels: { environment: "development" }, }, ]; // Calculate trends using our percentage change function const previousMonthCosts = [ { amount: 1150.25, currency: "USD" }, { amount: 95.75, currency: "USD" }, ]; let trendsAnalysis = `\n## Cost Trends Analysis\n\n`; mockCostData.forEach((cost, index) => { const previousCost = previousMonthCosts[index]?.amount || 0; const percentageChange = calculatePercentageChange( cost.cost.amount, previousCost, ); const changeDirection = percentageChange > 0 ? "📈" : "📉"; const changeIcon = Math.abs(percentageChange) > 20 ? "⚠️" : "✅"; trendsAnalysis += `**${cost.projectId} (${cost.serviceId}):** `; trendsAnalysis += `${changeIcon} ${changeDirection} ${percentageChange.toFixed(1)}% `; trendsAnalysis += `(${formatCurrency(previousCost)} → ${formatCurrency(cost.cost.amount)})\n`; }); let response = `# Cost Analysis\n\n`; response += `**Billing Account:** ${billingAccountName}\n`; response += `**Period:** ${startDate} to ${endDate}\n`; response += `**Grouped By:** ${groupBy}\n\n`; response += `⚠️ **Note:** This is a demonstration with mock data. `; response += `For actual cost analysis, you would need to:\n`; response += `1. Enable BigQuery billing export\n`; response += `2. Use Cloud Billing Report API\n`; response += `3. Query the billing export dataset\n\n`; response += formatCostData(mockCostData); response += trendsAnalysis; const totalCost = mockCostData.reduce( (sum, cost) => sum + cost.cost.amount, 0, ); response += `\n**Total Cost:** ${formatCurrency(totalCost)}\n`; return { content: [ { type: "text", text: response, }, ], }; } catch (error: any) { logger.error(`Error analysing costs: ${error.message}`); throw new GcpMcpError( `Failed to analyse costs: ${error.message}`, error.code || "UNKNOWN", error.status || 500, ); } },
• src/services/billing/tools.ts:655-679 (schema)

  Zod input schema defining the parameters for the tool: required billing account and dates, optional filters for project/service, and grouping option.
  inputSchema: { billingAccountName: z .string() .describe( "Billing account name (e.g., 'billingAccounts/123456-789ABC-DEF012')", ), startDate: z .string() .describe("Start date for cost analysis (ISO format: YYYY-MM-DD)"), endDate: z .string() .describe("End date for cost analysis (ISO format: YYYY-MM-DD)"), projectId: z .string() .optional() .describe("Optional project ID to filter costs"), serviceId: z .string() .optional() .describe("Optional service ID to filter costs"), groupBy: z .enum(["project", "service", "sku", "time"]) .default("service") .describe("Group costs by project, service, SKU, or time"), },
• src/services/billing/tools.ts:649-781 (registration)

  Registration of the 'gcp-billing-analyse-costs' tool on the MCP server using server.registerTool, including title, description, input schema, and handler function.
  server.registerTool( "gcp-billing-analyse-costs", { title: "Analyse Billing Costs", description: "Perform detailed cost analysis with trends and insights for Google Cloud billing data", inputSchema: { billingAccountName: z .string() .describe( "Billing account name (e.g., 'billingAccounts/123456-789ABC-DEF012')", ), startDate: z .string() .describe("Start date for cost analysis (ISO format: YYYY-MM-DD)"), endDate: z .string() .describe("End date for cost analysis (ISO format: YYYY-MM-DD)"), projectId: z .string() .optional() .describe("Optional project ID to filter costs"), serviceId: z .string() .optional() .describe("Optional service ID to filter costs"), groupBy: z .enum(["project", "service", "sku", "time"]) .default("service") .describe("Group costs by project, service, SKU, or time"), }, }, async ({ billingAccountName, startDate, endDate, projectId, serviceId, groupBy, }) => { try { logger.debug( `Analysing costs for billing account: ${billingAccountName}`, ); // Use project hierarchy: provided -> state manager -> auth default const actualProjectId = projectId || stateManager.getCurrentProjectId() || (await getProjectId()); // Note: This is a mock implementation since BigQuery billing export or // Cloud Billing Report API would be needed for actual cost data const mockCostData: CostData[] = [ { billingAccountName, projectId: actualProjectId || "example-project-1", serviceId: serviceId || "compute.googleapis.com", cost: { amount: 1250.5, currency: "USD" }, usage: { amount: 100, unit: "hours" }, period: { startTime: startDate, endTime: endDate }, labels: { environment: "production" }, }, { billingAccountName, projectId: actualProjectId || "example-project-2", serviceId: serviceId || "storage.googleapis.com", cost: { amount: 89.25, currency: "USD" }, usage: { amount: 500, unit: "GB" }, period: { startTime: startDate, endTime: endDate }, labels: { environment: "development" }, }, ]; // Calculate trends using our percentage change function const previousMonthCosts = [ { amount: 1150.25, currency: "USD" }, { amount: 95.75, currency: "USD" }, ]; let trendsAnalysis = `\n## Cost Trends Analysis\n\n`; mockCostData.forEach((cost, index) => { const previousCost = previousMonthCosts[index]?.amount || 0; const percentageChange = calculatePercentageChange( cost.cost.amount, previousCost, ); const changeDirection = percentageChange > 0 ? "📈" : "📉"; const changeIcon = Math.abs(percentageChange) > 20 ? "⚠️" : "✅"; trendsAnalysis += `**${cost.projectId} (${cost.serviceId}):** `; trendsAnalysis += `${changeIcon} ${changeDirection} ${percentageChange.toFixed(1)}% `; trendsAnalysis += `(${formatCurrency(previousCost)} → ${formatCurrency(cost.cost.amount)})\n`; }); let response = `# Cost Analysis\n\n`; response += `**Billing Account:** ${billingAccountName}\n`; response += `**Period:** ${startDate} to ${endDate}\n`; response += `**Grouped By:** ${groupBy}\n\n`; response += `⚠️ **Note:** This is a demonstration with mock data. `; response += `For actual cost analysis, you would need to:\n`; response += `1. Enable BigQuery billing export\n`; response += `2. Use Cloud Billing Report API\n`; response += `3. Query the billing export dataset\n\n`; response += formatCostData(mockCostData); response += trendsAnalysis; const totalCost = mockCostData.reduce( (sum, cost) => sum + cost.cost.amount, 0, ); response += `\n**Total Cost:** ${formatCurrency(totalCost)}\n`; return { content: [ { type: "text", text: response, }, ], }; } catch (error: any) { logger.error(`Error analysing costs: ${error.message}`); throw new GcpMcpError( `Failed to analyse costs: ${error.message}`, error.code || "UNKNOWN", error.status || 500, ); } }, );
• src/services/billing/types.ts:309-329 (helper)

  Helper function formatCostData used by the tool handler to generate a Markdown table from CostData array for the analysis report.
  export function formatCostData(costs: CostData[]): string { if (costs.length === 0) { return "No cost data available for the specified period."; } let result = "## Cost Analysis\n\n"; result += "| Project | Service | Cost | Usage | Period |\n"; result += "|---------|---------|------|-------|--------|\n"; for (const cost of costs) { const projectId = cost.projectId || "All Projects"; const serviceId = cost.serviceId || "All Services"; const formattedCost = formatCurrency(cost.cost.amount, cost.cost.currency); const usage = `${cost.usage.amount} ${cost.usage.unit}`; const period = `${new Date(cost.period.startTime).toLocaleDateString("en-AU")} - ${new Date(cost.period.endTime).toLocaleDateString("en-AU")}`; result += `| ${projectId} | ${serviceId} | ${formattedCost} | ${usage} | ${period} |\n`; } return result; }
• src/services/billing/types.ts:439-445 (helper)

  Helper function to calculate percentage change between current and previous costs, used for trends analysis in the tool.
  export function calculatePercentageChange( current: number, previous: number, ): number { if (previous === 0) return current > 0 ? 100 : 0; return ((current - previous) / previous) * 100; }