io.github.alexpota/cloudscope
Azure + GCP cost management: spending, forecasts, anomalies, budgets, idle resources, and tags.
Open source Open in the app JSON README (API)
About
Azure + GCP cost management: spending, forecasts, anomalies, budgets, idle resources, and tags.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- alexpota
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.3
- Stars
- 1
- Open pull requests
- 11
- Last push
- 2026-08-12T01:27:58Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.alexpota/cloudscope
README
# 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)