Skip to content

alexpota/cloudscope-mcp

BranchesTags

Repository files navigation

CloudScope MCP

Ask your AI about your cloud bill.

npm version MCP Registry Node.js TypeScript License: MIT

What you get

Ask once: "Give me this month's cost review" — and CloudScope runs the full workflow (spend, deltas, anomalies, idle resources, budgets, forecast) and hands back a decision-ready report, not raw numbers to interpret yourself:

TL;DR

Month-to-date Azure spend is $4,312 (May 1–29), tracking +11% vs April. The mover is App Service (+$280) — a new staging slot left running. 2 idle resources cost $94/month; prod-budget is at 78% with 2 days left. Top action: delete the orphaned managed disk → save $63/month.

Spend This Month

Service Cost %
Virtual Machines $2,140 49.6%
App Service $890 20.6%
Storage $612 14.2%
Redis Cache $410 9.5%
Networking $260 6.0%

vs Last Month

+$427 (+11%) overall. App Service +$280 drove most of it; everything else flat. → new staging-slot-2, created May 12, never torn down.

Idle & Wasted Resources

Resource Type $/month
orphaned-osdisk-01 Managed Disk $63
old-lb-ip Public IP $31

Budget Status

prod-budget — 78% used, $4,312 / $5,500, on track (2 days left).

Recommended Actions

  1. Delete orphaned-osdisk-01 (unattached 40 days) → $63/month
  2. Tear down staging-slot-2 if staging is idle → ~$280/month
  3. Release old-lb-ip (no binding) → $31/month

Illustrative example showing the report format. Run /cloudscope:monthly-cost-review against your own subscription for live numbers.

Install

Claude Code Cursor VS Code
claude mcp add cloudscope -- npx -y cloudscope-mcp Install Install

Azure is auto-detected from your az login session. GCP requires BigQuery billing export setup (see below).

Supported Providers

Provider Status
Azure ✅ Supported
GCP ✅ Supported
AWS Use AWS's official server

Prerequisites

Azure

  • Azure CLI installed and logged in (az login)
  • Cost Management Reader role on the subscription

GCP

  • gcloud CLI installed and logged in (gcloud auth application-default login)
  • Billing export to BigQuery enabled — this is a one-time manual setup step, not enabled by default (the detailed export is recommended for resource-level cost queries)
  • BigQuery Data Viewer + BigQuery Job User roles on the dataset project
  • Note: BigQuery on-demand queries cost $6.25 per TiB scanned (pricing). The first 1 TiB/month is free. Billing export tables are small — typical CloudScope queries cost <$0.01 each.

Configuration

Azure (zero-config)

CloudScope auto-detects your subscription from az login. Just add the server:

{
  "mcpServers": {
    "cloudscope": {
      "command": "npx",
      "args": ["-y", "cloudscope-mcp"]
    }
  }
}

To target a specific subscription, add an env block:

{
  "mcpServers": {
    "cloudscope": {
      "command": "npx",
      "args": ["-y", "cloudscope-mcp"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id"
      }
    }
  }
}
Advanced: Service Principal (CI/CD & automated environments)
Variable Description
AZURE_TENANT_ID Azure AD tenant ID
AZURE_CLIENT_ID App registration client ID
AZURE_CLIENT_SECRET App registration client secret

Set these alongside AZURE_SUBSCRIPTION_ID in the env block above.

GCP

GCP requires a BigQuery billing export table. Find your table name in GCP Console > Billing > Billing export > BigQuery export.

{
  "mcpServers": {
    "cloudscope": {
      "command": "npx",
      "args": ["-y", "cloudscope-mcp"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "my-project",
        "GCP_BILLING_TABLE": "my-project.my_dataset.gcp_billing_export_resource_v1_XXXXXX"
      }
    }
  }
}

Set GOOGLE_CLOUD_PROJECT to your GCP project ID. Override with GCP_PROJECT_ID if your billing dataset lives in a different project.

These variables apply only when using GCP; Azure-only users can skip them.

Variable Description Required
GOOGLE_CLOUD_PROJECT GCP project ID Yes
GCP_BILLING_TABLE Fully-qualified BigQuery table (project.dataset.table) Yes
GCP_PROJECT_ID Override project ID if different from GOOGLE_CLOUD_PROJECT No
GCP_BILLING_ACCOUNT_ID Billing account ID for budget monitoring No
GOOGLE_APPLICATION_CREDENTIALS Path to service account JSON key file No

Both Providers

{
  "mcpServers": {
    "cloudscope": {
      "command": "npx",
      "args": ["-y", "cloudscope-mcp"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
        "GOOGLE_CLOUD_PROJECT": "my-project",
        "GCP_BILLING_TABLE": "my-project.my_dataset.gcp_billing_export_resource_v1_XXXXXX"
      }
    }
  }
}

Azure is auto-detected from az login. Add AZURE_SUBSCRIPTION_ID to target a specific subscription.

Example Questions

  • "How much did Azure cost last month?"
  • "Show GCP spending by service for the last 7 days"
  • "Any cost anomalies this week on GCP?"
  • "What will Azure cost next month?"
  • "Show me cost optimization recommendations for GCP"
  • "Compare Azure and GCP costs across all projects and subscriptions"

Security

CloudScope is read-only. It cannot create, modify, or delete any cloud resources. Azure uses Cost Management Reader permissions. GCP uses BigQuery Data Viewer + Job User with no write access.

FAQ

Does this modify my cloud resources? No. Read-only access only.

Do I need a service principal? No. az login (Azure) or gcloud auth application-default login (GCP) works for local use.

Does the Azure Cost Management API cost money? No. It's free.

Do GCP BigQuery cost queries cost money? Yes, but typically <$0.01 per query ($6.25/TiB scanned, first 1 TiB/month free). See BigQuery pricing.

Can I use both Azure and GCP at the same time? Yes. Configure both sets of env vars and CloudScope queries whichever provider you specify in each tool call.

Development

git clone https://github.com/alexpota/cloudscope-mcp.git
cd cloudscope-mcp
npm install
npm run build
npm test
npx @modelcontextprotocol/inspector node dist/index.js

Reference

Tools

Most tools accept a provider parameter (azure or gcp); the provider-specific tools (list_subscriptions, list_projects, and the cross-account tools get_cross_subscription_costs / get_cross_project_costs) are fixed to their own cloud. The default provider is auto-detected based on which providers are configured.

Cost Analysis

Tool Description Key Parameters
get_cost_summary Spending breakdown by service, group, or region start_date, end_date, group_by
get_cost_by_tag Costs grouped by a tag/label key tag_key, start_date, end_date
compare_periods Side-by-side cost comparison of two date ranges period_a_start/end, period_b_start/end
top_spending_resources Most expensive individual resources days, limit
get_cross_subscription_costs Combined costs across Azure subscriptions subscription_ids, start_date, end_date
get_cross_project_costs Combined costs across GCP projects project_ids, start_date, end_date

Monitoring

Tool Description Key Parameters
detect_anomalies Find spending spikes vs previous period days, threshold
check_budgets Budget status, current spend, projected overage (none)
get_cost_forecast Predict spending based on current trends days

Optimization

Tool Description Key Parameters
list_recommendations Cost optimization suggestions (Azure Advisor / GCP Recommender) category
find_idle_resources Provisioned but unused resources with cost estimates (none)
find_untagged_resources Resources with no tags/labels (cost attribution gaps) (none)

Utility

Tool Description Key Parameters
get_current_date Today's date and current/previous month bounds (none)
list_subscriptions Azure subscriptions with active indicator (none)
list_projects GCP projects with active indicator (none)

Prompts

Guided workflows that produce structured reports. All prompts accept an optional provider argument (azure or gcp). In Claude Code, type /cloudscope: to see all prompts. In Claude Desktop, click the + button → Connectors → cloudscope.

Prompt Description Arguments
monthly-cost-review Complete monthly review: spending, last-month comparison, anomalies, top resources, budgets, forecast, savings opportunities provider (optional)
waste-audit Find wasted spend: top resources, optimization recommendations, at-risk budgets, total potential savings provider (optional)
cost-spike-investigation Root-cause analysis for a cost increase: which services, which resources, trend vs one-time, recommended actions days (optional), provider (optional)
executive-summary Brief non-technical cost summary for leadership: spend, trend, budget status, top drivers, forecast, key recommendation provider (optional)
chargeback-report Cost allocation by tag/label key for chargeback: spending per value, untagged resources, tagged vs untagged split, month-over-month tag_key (required), provider (optional)

License

MIT

About

Multi-cloud cost management MCP server (Azure + GCP). Read-only access to spending, anomalies, forecasts, budgets, and guided FinOps workflows. Ask your AI about your cloud bill.

mcpscope.dev

Topics

bigquery azure mcp gcp google-cloud cursor multi-cloud anomaly-detection claude cost-optimization cost-management finops cloud-cost azure-advisor model-context-protocol mcp-server claude-code cloud-billing budget-monitoring gcp-recommender

Resources

Readme

License

MIT license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 11

v0.3.3 Latest
May 29, 2026
+ 10 releases

Packages

 
 
 

Contributors

Languages