Build a GCP Cost Agent with ADK and MCP Toolbox for Databases to Analyze Your Cloud Spending
Cloud costs are one of the hardest things to keep track of. Whether you’re running a single project or managing dozens across an organization, digging into your Google Cloud Billing Export dataset in BigQuery often feels like writing the same SQL over and over again.
That’s where agents come in. Using the Agent Development Kit (ADK) and the MCP Toolbox for Databases, I built an agent that gives me conversational access to GCP cost data. Instead of wrangling queries and dashboards, I can now just ask:
- What was my total GCP cost for August 2025
- Show me project spending for September 2025.
- Was Compute Engine or Cloud Storage more expensive in September 2025?
And get answers instantly.
Want a video version of the tutorial, check out the video given below.
If you are looking to get started with MCP Toolbox for databases and Agent Development Kit, check out the resources given below.
Making Cloud Billing Data Usable
Google Cloud billing data is full of valuable details — monthly totals, project breakdowns, service costs, and more. But most people only ever see it inside the Cloud Console’s Billing section, which isn’t exactly the easiest place to work with. The screens are complex, insights are limited, and it’s tough to go beyond the defaults.
The first step to making this data useful is exporting it to BigQuery. Once it’s there, you get flexibility — but at a cost. Suddenly you’re dealing with SQL queries, nested schemas (credits, labels, etc.), and the need for technical know-how just to answer basic cost questions.
If you’re new to this part, check out my earlier blog on how to set up billing export to BigQuery:
The problem we’re solving here is simple: instead of clicking through the console or writing SQL every time, why not just talk to your billing data?
With the Agent Development Kit (ADK) and MCP Toolbox for Databases, I built an agent that plugs directly into your BigQuery billing export and gives you conversational access.
Ask it for your total costs, project-level breakdowns, or the most expensive service last month — and get clear answers instantly, with the right currency and units.
It’s a practical and interesting example of using agents for FinOps: turning something as complex as billing data into something you can simply ask questions about.
Use Case: Streamlining GCP Cost Analysis
Imagine a FinOps analyst needing a project cost breakdown. Traditionally, they’d navigate the console or write SQL. With GCPCostAgent, they ask,
Break down costs by project for August 2023
and receive:
Project A: $500 USD; Project B: $300 USD.
This eliminates console scrolling and SQL, making data accessible to all.
Prerequisites
- Google Cloud project with BigQuery/Vertex AI APIs enabled.
- Billing data exported (Learn how to?).
- A Python virtual environment. Create one using python -m venv env and activate it
(source env/bin/activate). Then, runpip install google-adkto install the required dependencies. gcloud auth application-default login
Step 1: Prepare your BigQuery Dataset
For this article we are going to be using the Cloud Billing Export dataset that can help developers easily understand their GCP costs by project, service, acount and much more. To know more about transferring your cloud billing data to BigQuery, check out the article given below.
Run a sample query to verify data:
SELECT
SUM(t.cost) + SUM( IFNULL( (
SELECT
SUM(c.amount)
FROM
UNNEST(t.credits) AS c), 0)) AS total_cost
FROM
`aryanpython`.`gcp_billing`.`gcp_billing_export_resource_v1_01E9B3_867BA2_437AC3` AS t;
Want a video version of the tutorial, check out the video given below.
Step 2: Define Your Tools (tools.yaml)
The MCP Toolbox for Databases requires a file called tools.yaml, which is a YAML file that defines which database you’re connecting to and which SQL queries will be exposed as tools. These tools query the cloud_billing_export table, abstracting schema complexity and enabling secure, parameterized access for the GCPCostAgent.
sources:
gcp_billing_bq:
kind: bigquery
project: aryanpython
tools:
get_monthly_cost_summary:
kind: bigquery-sql
source: gcp_billing_bq
description: "Retrieves a summary of Google Cloud costs for a specific invoice month."
parameters:
- name: invoice_month
type: string
description: "The invoice month in YYYYMM format (e.g., 202307)."
statement: |
SELECT
invoice.month,
SUM(cost) + SUM( IFNULL( (SELECT SUM(c.amount) FROM UNNEST(credits) c), 0)) AS total_cost,
currency
FROM
`aryanpython.gcp_billing.gcp_billing_export_resource_v1_01E9B3_867BA2_437AC3`
WHERE
invoice.month = @invoice_month
GROUP BY
invoice.month, currency
ORDER BY
invoice.monthWe start off by declaring our sources for the tools followed by creating our first tool get_monthly_cost_summary. This tool fetches a high-level summary of your Google Cloud costs for a specific invoice month, including total cost and currency. It’s perfect for getting a quick monthly overview without digging through the console.
get_cost_by_project:
kind: bigquery-sql
source: gcp_billing_bq
description: "Retrieves a breakdown of Google Cloud costs by project for a specific invoice month."
parameters:
- name: invoice_month
type: string
description: "The invoice month in YYYYMM format (e.g., 202307)."
statement: |
SELECT
project.name,
project.id,
SUM(cost) as final_cost,
currency
FROM
`aryanpython.gcp_billing.gcp_billing_export_resource_v1_01E9B3_867BA2_437AC3`
WHERE
invoice.month = @invoice_month
GROUP BY
1, 2, currency
ORDER BY
final_cost DESCThe get_cost_by_project tool executes a BigQuery SQL query to group costs from the cloud_billing_export table by project for a given invoice month (in YYYYMM format). It sums the costs and includes the currency, ordering results from highest to lowest cost for easy identification of top spenders. The output includes project.name, project.id, final_cost, and currency for comprehensive, currency-aware breakdowns.
This tool aligns with the agent’s workflow for costs by project, enabling queries like Break down costs by project in August 2023.
get_cost_by_service:
kind: bigquery-sql
source: gcp_billing_bq
description: "Retrieves a breakdown of Google Cloud costs by service for a specific invoice month."
parameters:
- name: invoice_month
type: string
description: "The invoice month in YYYYMM format (e.g., 202307)."
statement: |
SELECT
service.description,
SUM(cost) as final_cost,
currency
FROM
`aryanpython.gcp_billing.gcp_billing_export_resource_v1_01E9B3_867BA2_437AC3`
WHERE
invoice.month = @invoice_month
GROUP BY
1, currency
ORDER BY
final_cost DESCThis tool breaks down costs by service for a specific invoice month, including service descriptions, final costs, and currency. It calculates the final cost by summing costs and orders results descending to highlight top consumers, including the currency for accurate reporting.
It removes the need for console filters or manual grouping, making it easier for FinOps teams to spot trends in service usage without the hassle of complex interfaces or SQL scripting.
toolsets:
gcp-cost-agent-tools:
- get_monthly_cost_summary
- get_cost_by_project
- get_cost_by_serviceAll tools are bundled into one toolset gcp-cost-agent-tools, to keep everything organized and easy to load into the agent for seamless cost analysis.
Run the Toolbox Server
./toolbox --tools-file="tools.yaml"
Step 3: Build the ADK-powered Agent
Now that we’ve configured the MCP Toolbox with our tools.yaml file, it’s time to bring the GCPCostAgent to life. The GCPCostAgent is designed to handle a variety of cost-related questions by following structured workflows. Built with Google Cloud’s Agent Development Kit (ADK) and powered by the MCP Toolbox for Databases, this agent lets you chat with your Cloud Billing Export data stored in BigQuery — without the need to navigate intricate console screens or write complex SQL queries.
Whether you’re a FinOps professional tracking monthly spend or a developer curious about project costs, this agent delivers clear, concise answers.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
# Initialize the toolbox client to connect to the tool server
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load the toolset defined in your tools.yaml
tools = toolbox.load_toolset('gcp-cost-agent-tools')We start off by importing the ADK framework for building agents followed importing from toolbox_core import ToolboxSyncClient that brings in the MCP Toolbox client for interacting with the tool server.
We then create a client to connect to the local MCP server (running on port 5000), where tools.yaml is served. This link enables the agent to access the gcp-cost-agent-tools toolset.
Once we initialise, we move to load the defined tools into the agent using toolbox.load_toolset(‘gcp-cost-agent-tools’) .
# Define the root agent
root_agent = Agent(
name="GCPCostAgent",
model="gemini-2.5-flash",
description=(
"An agent that provides insights into your Google Cloud Platform (GCP) costs "
"by querying your billing data in BigQuery. It can retrieve total monthly "
"costs and provide breakdowns of spending by project or by service."
),
instruction=(
"You are a Google Cloud Cost expert. Your purpose is to provide accurate cost and usage "
"information by querying the GCP billing export data in BigQuery.\n\n"
"**ALWAYS follow these instructions and workflows step-by-step:**\n\n"
"1. **Determine the Time Period:**\n"
" - If the user specifies a date range (e.g., 'yesterday', 'last week', 'since June 1st'), use the `get_cost_by_date_range` tool. You must provide a `start_date` and `end_date` in 'YYYY-MM-DD' format.\n"
" - If the user specifies a month (e.g., 'last month', 'in August'), use a tool that requires an `invoice_month`. Calculate the month in `YYYYMM` format.\n"
" - If no time period is specified, you MUST ask the user for clarification.\n\n"
"2. **Select the Right Tool based on the user's request:**\n"
" - **For monthly costs:**\n"
" - For a total summary: `get_monthly_cost_summary`\n"
" - For a breakdown by project: `get_cost_by_project`\n"
" - For a breakdown by service: `get_cost_by_service`\n"
" - **For costs in a specific date range:**\n"
" - Use `get_cost_by_date_range`.\n"
" - **For detailed breakdowns within a month:**\n"
" - If the user asks for a breakdown by SKU for a specific service, use `get_cost_by_sku`. You must know the `service_description`.\n"
" - **For usage information:**\n"
" - If the user asks for usage amount for a specific service, use `get_usage_by_service`. You must know the `service_description`.\n\n"
"3. **Present the Information Clearly:**\n"
" - **IMPORTANT**: When presenting any cost, you MUST also state the currency code returned by the tool (e.g., 'The total cost was 15000 INR'). Do not assume the currency is USD.\n"
" - When presenting usage, you MUST state the unit (e.g., 'Total usage was 500.5 GiB').\n"
" - When providing breakdowns, present the information in a clear, readable list, ordered from most to least expensive/used.\n\n"
"4. **Handle Errors and Empty Results:**\n"
" - If a tool returns an error or an empty result, inform the user. For monthly queries, advise them to check the `invoice_month`. For all queries, remind them to ensure the `project` and `table name` in `tools.yaml` are correct."
),
tools=tools,
)This segment creates the GCPCostAgent using the Agent class from ADK, using the gemini 2.5 flash model for natural language processing and reasoning. We declared the description and instruction set that provides detailed instructions and information on handling various user queries.
The workflows ensure consistency and accuracy, transforming inaccessible GCP billing data into a dynamic resource for users and enterprises.
Run and Test the Agent
To run locally, start the MCP Toolbox for Databases server and execute the adk web command. For production, deploy to Vertex AI Agent Engine or Cloud Run for scalability. This setup enables conversational queries, turning dead billing data into actionable insights without manual SQL or API hassles.
Our first interaction is fundamental: understanding what the agent can actually do. This tests the agent’s ability to summarize its description and instruction_text.
Prompt: Hello, What can you do for me?
The agent provides a concise summary of its abilities, drawing from its description and instruction set.Basis Questions
We start of by testing the functionality of retrieving the total cost, credits, and final cost for a given invoice month.
Prompt: What was my total bill in September 2025?
The agent successfully gives my my total cost for August 2025. Next we test the get_cost_by_project tool to fetch costing for each project.
Prompt: Which projects cost the most in August 2025?
Now we will retrieve a breakdown of costs by service for a given invoice month.
Prompt: Which services were the most expensive in August 2025?
Conclusion
With MCP Toolbox for Databases and ADK, we move from static billing screens and manual queries to a conversational way of understanding costs. Instead of navigating the Google Cloud console or writing SQL, you can ask the agent questions and get instant answers. This approach doesn’t just simplify analysis — it opens the door for FinOps agents that are not only conversational today but could be autonomous tomorrow, acting on insights in real time.
You can check out the code by checking out the link given below.
Feel free to reach out if you have any issues/feedback at aryanirani123@gmail.com.
