cloudscope-mcp

# CloudScope MCP > Ask your AI about your cloud bill. [](https://www.npmjs.com/package/cloudscope-mcp) [](https://glama.ai/mcp/servers/alexpota/cloudscope-mcp) [](https://nodejs.org) [](https://www.typescriptlang.org) [](LICENSE) ## 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](https://cursor.com/en/install-mcp?name=cloudscope&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsb3Vkc2NvcGUtbWNwIl19) | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=cloudscope&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsb3Vkc2NvcGUtbWNwIl19) | > 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](https://github.com/awslabs/mcp/tree/main/src/billing-cost-management-mcp-server) | ## Prerequisites ### Azure - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed and logged in (`az login`) - **Cost Management Reader** role on the subscription ### GCP - [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and logged in (`gcloud auth application-default login`) - [Billing export to BigQuery](https://cloud.google.com/billing/docs/how-to/export-data-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](https://cloud.google.com/bigquery/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: ```json { "mcpServers": { "cloudscope": { "command": "npx", "args": ["-y", "cloudscope-mcp"] } } } ``` To target a specific subscription, add an `env` block: ```json { "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**. ```json { "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 ```json { "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](https://cloud.google.com/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 ```bash 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](LICENSE)