Skip to main content
Glama
vamsitejeswar

azure-billing-mcp-server

by vamsitejeswar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Azure Billing MCP Server

MCP server for Azure spend, cost analysis, and billing via the Azure Cost Management and Billing APIs. Deployed to Google Cloud Run and connected to Gemini Enterprise.

Architecture

User in Gemini Enterprise
        │
        ▼
Gemini Enterprise ──► Entra ID OAuth (login.microsoftonline.com)
        │  receives access token (scope: api://<client-id>/mcp.access)
        ▼
MCP Server on Cloud Run  (access gated by Cloud Run IAM)
  BearerTokenMiddleware captures the token for audit logging only —
  it is NOT forwarded to Azure (wrong audience for management.azure.com)
        │
        ▼
  Server's own service principal ──► Azure Cost Management + Billing APIs
        │
        ▼
Response back to Gemini Enterprise ──► User

The Entra ID app used for GE login and the service principal used for billing are two separate identities. The incoming token is logged for visibility but never used to call Azure.

Related MCP server: Azure FinOps Elite

Files

server.py            # FastMCP app, Azure client, all 11 tools, entrypoint
requirements.txt
Dockerfile
deploy_cloudrun.sh   # build image, deploy to Cloud Run, grant IAM
.env.example         # for local development
SETUP.md             # complete step-by-step setup guide for clients

Tools (11 total)

Cost Management

Tool

Description

list_subscriptions

List all accessible Azure subscriptions

query_costs

General-purpose cost query (timeframe, granularity, grouping)

get_cost_by_service

Cost breakdown by Azure service

get_cost_by_resource_group

Cost breakdown by resource group

get_daily_cost_trend

Day-by-day cost time series

get_top_resources_by_cost

Top N most expensive resources

Billing API

Tool

Description

get_billing_accounts

List billing accounts

get_billing_periods

List billing periods history

get_invoices

List invoices for a billing account

get_usage_details

Detailed usage records by date range

get_budgets

Budget limits and current spend vs limit

All tools are read-only (readOnlyHint=True).

Two Separate Credentials

Credential

Purpose

Used by

Azure service principal (AZURE_CLIENT_ID)

Queries Azure billing APIs

The MCP server itself

Entra ID app registration (gemini-enterprise-mcp)

OAuth login screen for GE

Gemini Enterprise

Do NOT mix these up — they serve different roles.

Gemini Enterprise Setup

MCP Server URL

https://<your-cloud-run-url>/mcp

Printed by deploy_cloudrun.sh after deploy.

Authentication Settings (fill in GE form)

Field

Value

MCP Server URL

https://<cloud-run-url>/mcp

Authorization URL

https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize

Token URL

https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token

Client ID

Application (client) ID of gemini-enterprise-mcp app

Client Secret

Secret from gemini-enterprise-mcp app — NOT the service principal secret

Scopes

api://<client-id>/mcp.access offline_access

Enable PKCE

Leave unchecked

MCP Agent Instructions (paste into GE)

You have access to Azure Cost Management and Billing tools for querying actual
Azure spend, invoices, budgets, and usage. All tools are read-only.
If the user doesn't specify a subscription, call list_subscriptions first.
For invoice queries, call get_billing_accounts first.
Default timeframe is "MonthToDate" unless the user asks for a different period.

Required Redirect URIs (add in Entra ID App Registration → Authentication)

https://vertexaisearch.cloud.google.com/console/oauth/default_oauth.html
https://vertexaisearch.cloud.google.com/oauth-redirect

Local Development

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
python server.py        # runs at http://0.0.0.0:8080/mcp

Deploy to Cloud Run

# 1. Fill in deploy_cloudrun.sh variables:
#    GCP_PROJECT, COST_MGMT_TENANT_ID, COST_MGMT_CLIENT_ID

# 2. Store the Azure client secret in Secret Manager:
printf '%s' 'YOUR_SECRET' | gcloud secrets create Azure_secret_value \
  --project <your-gcp-project-id> --data-file=-

# 3. Deploy:
bash deploy_cloudrun.sh

For the full step-by-step client setup guide including Azure Portal screenshots, see SETUP.md.

Subscription Type Requirement

The Cost Management and Billing APIs require a paid commercial Azure subscription:

✅ Works

❌ Does NOT work

Pay-As-You-Go

Free Trial

Enterprise Agreement (EA)

Visual Studio / Dev/Test

Microsoft Customer Agreement (MCA)

CSP / Sponsored

Troubleshooting

Error

Cause

Fix

Failed to obtain refresh token

Wrong Client Secret in GE form

Use the gemini-enterprise-mcp secret, not the service principal secret

Failed to load actions in GE

Cloud Run server not starting

Re-grant Secret Manager permission to the compute service account

doesn't have valid WebDirect/AIRS offer type

Free Trial subscription

Upgrade to Pay-As-You-Go

Invalid tenant ID on startup

Placeholder credentials in deploy script

Fill in real COST_MGMT_TENANT_ID and COST_MGMT_CLIENT_ID

Permission denied on secret

Cloud Run SA lacks Secret Manager access

Run gcloud secrets add-iam-policy-binding for the compute SA

403 Forbidden

GE service account missing invoker role

Re-run the IAM grant in deploy_cloudrun.sh

AuthorizationFailed on billing tools

Missing Billing Reader role

Assign Billing Reader role to the service principal in Azure Portal

Tools return empty []

Service principal has no subscription access

Assign Cost Management Reader role using the service principal's Object ID

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • Azure FinOps Elite

    mazhar480
    A
    license
    Not graded
    quality
    D
    maintenance
    Production-grade MCP server for enterprise Azure cost optimization, enabling spend anomaly detection, multi-tenant auditing, budget validation, and compliance-aware recommendations.
    1
    MIT

  • azure-cost-mcp

    MO2k4
    F
    license
    B
    quality
    D
    maintenance
    An MCP server that gives Claude live access to Azure pricing and cost data — retail prices, VM comparisons, reservation analysis, architecture estimates, and actual subscription spend.
    9
    -