cloudscope-mcp

CloudScope MCP

Ask your AI about your cloud bill.

    

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"
      }
    }
  }
}

<details> <summary>Advanced: Service Principal (CI/CD & automated environments)</summary>

| 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.

</details>

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