Azure FinOps MCP Server

An MCP server that gives LLM clients (Claude Desktop, Claude Code, VS Code, Cursor) conversational access to Azure cost analysis, budget tracking, forecasting, and resource optimization — across multiple subscriptions.

Tools

Discovery

Cost Analysis

Budgets

Optimization

Forecasting

Quick Install

pip install azure-finops-mcp

Then add it to your MCP client config using the installed command — no cloning needed:

{
  "mcpServers": {
    "azure-finops": {
      "command": "azure-finops-mcp",
      "env": {
        "AZURE_ALLOWED_SUBSCRIPTIONS": "sub-id-1,sub-id-2",
        "AZURE_DEFAULT_SUBSCRIPTION": "sub-id-1"
      }
    }
  }
}

See the Client Configuration section below for per-client config file locations.

Prerequisites

• Python 3.11+
• Azure CLI installed and logged in (az login)

Azure RBAC Permissions

The identity running this server (your user, a service principal, or a managed identity) needs three roles assigned on each subscription you want to query:

Assign via Azure CLI

SUBSCRIPTION_ID="<your-subscription-id>"
PRINCIPAL_ID="<object-id-of-user-sp-or-managed-identity>"

for ROLE in "Cost Management Reader" "Reader" "Monitoring Reader"; do
  az role assignment create \
    --assignee "$PRINCIPAL_ID" \
    --role "$ROLE" \
    --scope "/subscriptions/$SUBSCRIPTION_ID"
done

Repeat for each subscription listed in AZURE_ALLOWED_SUBSCRIPTIONS.

Local development (your own user)

az login
az account set --subscription "<your-subscription-id>"

# Check your object ID
az ad signed-in-user show --query id -o tsv

Your user already has these roles if you're a subscription Owner or Contributor. If not, ask your Azure admin to assign them.

Managed Identity (Container Apps deployment)

After deploying with deploy.sh, the script automatically assigns these three roles to the Container App's system-assigned managed identity on each allowed subscription. No credentials or secrets are needed — DefaultAzureCredential picks up the managed identity automatically at runtime.

Install

git clone <your-repo-url> azure-finops-mcp
cd azure-finops-mcp

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .

cp .env.example .env
# Edit .env: set your subscription IDs

Configure .env

# Required: comma-separated subscription IDs the server may query
AZURE_ALLOWED_SUBSCRIPTIONS=sub-id-1,sub-id-2,sub-id-3

# Required: default subscription (must be in the list above)
AZURE_DEFAULT_SUBSCRIPTION=sub-id-1

Test with MCP Inspector

The Inspector is a web UI that lets you call tools interactively and see raw JSON-RPC messages. Always test here before connecting to Claude Desktop.

# Use the venv's python3 explicitly — the Inspector launches a subprocess
# and needs the binary that has mcp + azure SDKs installed.
npx @modelcontextprotocol/inspector $(which python3) -m azure_finops_mcp.server

In the Inspector UI:

1. Verify Transport Type is STDIO
2. Click Connect — should succeed and show "azure-finops" as the server name
3. Navigate to Tools, click List Tools — you should see all 15 tools
4. Try list_subscriptions first (no arguments needed)
5. Try get_month_to_date_cost (no arguments needed — uses default sub)

Client Configuration

Find the absolute path to your venv's Python first — you'll need it in every config below:

# With your venv activated:
which python3
# e.g. /Users/yourname/azure-finops-mcp/.venv/bin/python3

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "azure-finops": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "azure_finops_mcp.server"],
      "env": {
        "AZURE_ALLOWED_SUBSCRIPTIONS": "sub-1,sub-2,sub-3",
        "AZURE_DEFAULT_SUBSCRIPTION": "sub-1",
        "FINOPS_CACHE_TTL_SECONDS": "900"
      }
    }
  }
}

Restart Claude Desktop. A tool icon in the chat input confirms the server connected.

VS Code (GitHub Copilot / Agent mode)

Create .vscode/mcp.json in your workspace (or add to user settings.json under "mcp"):

{
  "servers": {
    "azure-finops": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "azure_finops_mcp.server"],
      "env": {
        "AZURE_ALLOWED_SUBSCRIPTIONS": "sub-1,sub-2,sub-3",
        "AZURE_DEFAULT_SUBSCRIPTION": "sub-1",
        "FINOPS_CACHE_TTL_SECONDS": "900"
      }
    }
  }
}

Requires VS Code 1.99+ with the GitHub Copilot extension. Open the Chat panel, switch to Agent mode, and the azure-finops tools will appear automatically.

Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "azure-finops": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "azure_finops_mcp.server"],
      "env": {
        "AZURE_ALLOWED_SUBSCRIPTIONS": "sub-1,sub-2,sub-3",
        "AZURE_DEFAULT_SUBSCRIPTION": "sub-1",
        "FINOPS_CACHE_TTL_SECONDS": "900"
      }
    }
  }
}

Or add it via Cursor Settings → MCP → Add new global MCP server. Restart Cursor. The tools appear in Cursor's Agent/Composer panel.

Claude Code (CLI)

claude mcp add azure-finops \
  /absolute/path/to/.venv/bin/python3 \
  -m azure_finops_mcp.server \
  -e AZURE_ALLOWED_SUBSCRIPTIONS=sub-1,sub-2,sub-3 \
  -e AZURE_DEFAULT_SUBSCRIPTION=sub-1

Remote HTTP (after deploying to Azure Container Apps)

All clients support connecting to the deployed server over HTTP — no local Python needed:

Claude Desktop / Cursor — add to the same config files above:

{
  "mcpServers": {
    "azure-finops": {
      "type": "http",
      "url": "https://<your-container-app-fqdn>/mcp"
    }
  }
}

VS Code — in .vscode/mcp.json:

{
  "servers": {
    "azure-finops": {
      "type": "http",
      "url": "https://<your-container-app-fqdn>/mcp"
    }
  }
}

Claude Web — Settings → Integrations → Add → https://<your-container-app-fqdn>/mcp

Example Prompts

Try these once connected:

• "What are our allowed subscriptions?"
• "What's our total month-to-date spend across all subscriptions?"
• "Which 10 services cost the most on our prod subscription last month?"
• "Break down last quarter's spend by the costcenter tag."
• "Are any budgets close to breaching?"
• "Show me idle resources across all our subscriptions."
• "What does Azure Advisor recommend for cost savings?"
• "Is VM my-analytics-vm actually being used? Check its CPU over 14 days."
• "Compare our forecast for this month against our budgets."

Architecture

Claude Desktop ◄─┐
VS Code        ◄─┤
Cursor         ◄─┼──stdio / HTTP──► Azure FinOps MCP Server ◄──REST──► Azure APIs
Claude Code    ◄─┤                        │
Claude Web     ◄─┘                        ├── config.py          ← env + allowlist
                                          ├── azure_clients.py   ← shared credential
                                          ├── cache.py           ← TTL cache
                                          ├── server.py          ← FastMCP + registration
                                          └── tools/
                                              ├── subscriptions  ← discovery
                                              ├── cost           ← queries + portfolio
                                              ├── budgets        ← budget status
                                              ├── optimization   ← idle + advisor + metrics
                                              └── forecast       ← predictions

Key design decisions

Narrow tools over flexible tools. The LLM picks among well-named tools far better than it constructs complex query objects. 15 purpose-built tools beats 3 configurable ones.

Subscription allowlist. A frozenset loaded from env. Every tool calls resolve_subscription() which refuses any ID not in the list. Prevents the LLM from querying unauthorized subscriptions — important for prompt injection defense.

Portfolio tools catch per-sub errors. When querying 5+ subscriptions, one might have different RBAC or be in a weird state. Portfolio tools (get_portfolio_*) wrap each sub in try/except so partial results are returned with errors listed separately.

Cache on Cost Management only. Cost queries are expensive and rate-limited (~30 req/min per tenant). Cost data updates hourly at best. Default 15-minute TTL trades almost nothing in freshness for significant rate-limit headroom. Resource Graph and Advisor are fast and cheap — no caching needed.

Structured returns, not prose. Tools return dicts with columns/rows/metadata. The LLM narrates them naturally. This avoids encoding English into tool responses (which makes them brittle to prompt changes).

Deploying to Azure (Remote Mode)

For team-wide access, deploy as a remote HTTP server:

1. Transport swap in server.py:

   python

   Copy

   mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)
   

2. Dockerfile:

   Dockerfile

   Copy

   FROM python:3.12-slim
   WORKDIR /app
   COPY . .
   RUN pip install --no-cache-dir -e .
   CMD ["azure-finops-mcp"]
   

3. Deploy to Azure Container Apps with a user-assigned managed identity.

4. Grant RBAC to the managed identity (same 3 roles: Cost Management Reader, Reader, Monitoring Reader) on each subscription.

5. Add auth via APIM or Azure Front Door + Entra ID. MCP supports OAuth for remote servers.

6. DefaultAzureCredential picks up the managed identity automatically — no code changes needed.

Troubleshooting