Analyse Billing Costs
gcp-billing-analyse-costsAnalyze Google Cloud billing costs to identify trends, filter by project or service, and optimize spending with detailed insights.
Instructions
Perform detailed cost analysis with trends and insights for Google Cloud billing data
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| billingAccountName | Yes | Billing account name (e.g., 'billingAccounts/123456-789ABC-DEF012') | |
| startDate | Yes | Start date for cost analysis (ISO format: YYYY-MM-DD) | |
| endDate | Yes | End date for cost analysis (ISO format: YYYY-MM-DD) | |
| projectId | No | Optional project ID to filter costs | |
| serviceId | No | Optional service ID to filter costs | |
| groupBy | No | Group costs by project, service, SKU, or time | service |
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, ); } }, - 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, ); } }, ); - 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; } - 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; }