# Azure FinOps MCP Server

[![PyPI version](https://img.shields.io/pypi/v/azure-finops-mcp-server.svg)](https://pypi.org/project/azure-finops-mcp-server/)
[![Python Versions](https://img.shields.io/pypi/pyversions/azure-finops-mcp-server.svg)](https://pypi.org/project/azure-finops-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Architecture](https://img.shields.io/badge/Architecture-100%25-brightgreen)](docs/architecture-validation-report.md)
[![Tests](https://img.shields.io/badge/Tests-97.7%25-green)](tests/)
[![Security](https://img.shields.io/badge/Security-Production%20Ready-blue)](security-report.json)

An MCP (Model Context Protocol) server that brings powerful Azure FinOps capabilities directly into your AI assistant. Analyze cloud costs, audit for waste, and get budget insights using natural language, all while keeping your credentials secure on your local machine.

### Why Use the Azure FinOps MCP Server?

Managing Azure costs can be complex. Finding answers to questions like "What did we spend on Storage last month?" or "Do we have any stopped VMs?" often requires navigating the Azure Portal or writing scripts.

This server bridges that gap by connecting the powerful, natural language understanding of an LLM directly to your Azure subscription's financial data. You can ask complex questions and get immediate, actionable insights without ever leaving your chat interface.

#### Use Cases:

> **Prompt on Claude Desktop:** "Get `usage-type` based cost for all my Azure subscriptions for the last 90 days. And get the `audit report` for all subscriptions for region `eastus`. Make a finops report with data in minimalistic way and keep it professional."

![alt text](Claude_Desktop.png)

> **Prompt on Amazon Q CLI:** "Could you use `azure-finops` mcp server and get cost data for each month in the last 6 months for `subscription Production` and present the data in a tabular format highlighting how the total cost and cost for each service has changed every month?"

![alt text](<Amazon Q CLI.png>)

> **Prompt on Claude Desktop:** "Generate a comprehensive finops report for management using all the tools available in the Azure FinOps MCP server. Use all the available subscriptions and use the region eastus wherever required."

![alt text](<Claude - FinOps Report.png>)

#### Other sample reports generated by Claude using Azure FinOps MCP Server

> **<a href="https://ravikiranvm.github.io/finops-usage-report/" target="_blank" rel="noopener noreferrer">Network Usage & Cost Analysis Report</a>**


> **<a href="https://ravikiranvm.github.io/finops-comprehensive/" target="_blank" rel="noopener noreferrer">Comprehensive FinOps Report</a>**

---

## 🚀 What's New in v2.0.0

- **100% Architecture Compliance**: Achieved perfect score (142/142) in architecture validation
- **Performance**: 4.9x faster with parallel processing and optimized batch operations
- **Security**: All high-severity issues resolved, production-ready security posture
- **Modular Design**: Refactored into focused, maintainable modules (<50 lines per function)
- **Enhanced Testing**: 97.7% test coverage with comprehensive unit and integration tests
- **Full CI/CD**: GitHub Actions pipeline with automated testing and deployment
- **Better Error Handling**: Retry logic, circuit breakers, and graceful degradation

[View Full Release Notes](RELEASE_NOTES.md)

---

## Table of Contents

1.  [What is an MCP Server?](#what-is-an-mcp-server)
2.  [Why Use the Azure FinOps MCP Server?](#why-use-the-azure-finops-mcp-server)
3.  [Key Features](#key-features)
4.  [Prerequisites](#-prerequisites)
    *   [General Requirements](#general-requirements)
    *   [Azure Requirements & IAM Permissions](#azure-requirements--iam-permissions)
5.  [Installation](#-installation)
6.  [Configuration](#-configuration)
    *   [Step 1: Azure CLI Setup](#step-1-azure-cli-setup)
    *   [Step 2: MCP Client Setup (Claude for Desktop)](#step-2-mcp-client-setup-claude-for-desktop)
7.  [Usage & Example Prompts](#-usage--example-prompts)
    *   [Use Case: Cost & Usage Analysis](#use-case-cost--usage-analysis)
    *   [Use Case: FinOps Waste & Savings Audit](#use-case-finops-waste--savings-audit)
8.  [Tool Reference](#-tool-reference)
    *   [`get_cost`](#get_cost)
    *   [`run_finops_audit`](#run_finops_audit)
9.  [Cost Considerations](#-cost-considerations)
10. [Development & Contributing](#-development--contributing)
11. [License](#-license)

---

### Key Features

-   **Detailed Cost Analysis**: Query your Azure cost data using tags, time ranges, and service groupings.
-   **Automated FinOps Audit**: Instantly find common sources of cloud waste, such as stopped VMs, unattached Managed Disks, and unassociated Public IPs etc.
-   **Budget Monitoring**: Check the status of your Azure Budgets to see if you are on track, over budget, or forecasted to exceed your limits.
-   **Multi-Subscription & Multi-Region**: Seamlessly query across any or all of your Azure subscriptions and regions in a single command.
-   **Secure by Design**: Your Azure credentials **never leave your machine**. The server runs locally and uses your existing Azure CLI configuration to make API calls directly to Azure.

### Prerequisites

#### General Requirements

-   **Python 3.10+**: Ensure you have a compatible Python version installed.
-   **MCP Client**: An application that supports MCP. This guide uses [Claude for Desktop](https://claude.ai/download) as the example.

#### Azure Requirements & IAM Permissions

-   **Azure CLI**: The [Azure CLI must be installed](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) on your machine.
-   **Azure Subscription(s)**: You need at least one Azure subscription with active credentials.
-   **Azure Permissions**: The Azure identity (Service Principal or User) requires specific read-only permissions to function correctly.

Your Azure identity needs the following built-in roles or equivalent custom permissions. These permissions are **read-only** and grant access only to the necessary services.

**Required Azure Roles:**
- **Cost Management Reader**: For accessing cost and usage data
- **Reader**: For accessing resource information (VMs, Disks, IPs)

Alternatively, create a custom role with these permissions:
- `Microsoft.CostManagement/*/read`
- `Microsoft.Consumption/*/read`
- `Microsoft.Compute/virtualMachines/read`
- `Microsoft.Compute/virtualMachines/instanceView/read`
- `Microsoft.Compute/disks/read`
- `Microsoft.Network/publicIPAddresses/read`
- `Microsoft.Resources/subscriptions/read`
- `Microsoft.Resources/subscriptions/resourceGroups/read`

### Installation

There are several ways to install the Azure FinOps MCP Server:

### Option 1: Using uv (Recommended - Fast Python Package Manager)
[uv](https://github.com/astral-sh/uv) is a modern Python package installer and resolver that's extremely fast.

```bash
# Install uv if you don't have it yet
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create project directory
mkdir azure-finops-mcp-server && cd azure-finops-mcp-server

# Create and activate python virtual environment
uv venv && source .venv/bin/activate

# Install azure-finops-mcp-server
uv pip install azure-finops-mcp-server
```

### Option 2: Using pipx
```bash
pipx install azure-finops-mcp-server
```

If you don't have `pipx`, install it with:

```bash
python -m pip install --user pipx
python -m pipx ensurepath
```

### Option 3: From Source
```bash
# Clone the repository
git clone https://github.com/julianobarbosa/azure-finops-mcp-server.git
cd azure-finops-mcp-server

# Create and activate python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install using pip
pip install -e .
```

### Configuration

#### Step 1: Azure CLI Setup

If you haven't already, login to Azure and set up your subscriptions:

```bash
# Login to Azure
az login

# List available subscriptions
az account list

# Set a default subscription (optional)
az account set --subscription "Your Subscription Name"
```

The Azure CLI will handle authentication through your browser or device code flow. Your credentials are securely stored and managed by Azure CLI.

#### Step 2: MCP Client Setup (Claude for Desktop)

To use this server with Claude for Desktop, you need to tell the application how to run it.

1.  Open your Claude for Desktop configuration file. It's located at:
    *   **macOS / Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    *   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2.  Add the following entry to the `mcpServers` object. If the file doesn't exist or is empty, you'll need to create the JSON structure.

    ```json
    {
      "mcpServers": {
        "azure_finops": {
          "command": "azure-finops-mcp-server",
          "args": []
        }
      }
    }
    ```

3.  Save the file and **completely restart Claude for Desktop**.

After restarting, the server will launch in the background, and its tools will be available to Claude.

> ⚠️ **Note:**  
> After installing this tool (e.g., via `uv pip install azure-finops-mcp-server`), ensure the `azure-finops-mcp-server` command is available in your system's `PATH`.  
> 
> To check where it's installed, run:
> 
> ```bash
> which azure-finops-mcp-server
> ```
>
> If it returns a path like `/Users/yourname/.local/bin/azure-finops-mcp-server`, but it's **not in your PATH**, you have two options:
>
> - If using pipx: Run `pipx ensurepath` and restart your terminal, **or**
> - If using uv: Ensure your virtual environment is activated, **or**
> - Use the full path in your `mcpServers` config:
>
> ```json
> {
>   "mcpServers": {
>     "azure_finops": {
>       "command": "/full/path/to/azure-finops-mcp-server",
>       "args": []
>     }
>   }
> }
> ```

### Usage & Example Prompts

You can now ask questions about your Azure finances in plain English.

#### Use Case: Cost & Usage Analysis

> **Basic Query:**
> "Show me my Azure costs for the `Production` subscription this month."

> **Time-Range Query:**
> "get azure cost for my `Development` subscription for the last 14 days"

> **Filtered & Grouped Query:**
> "What was the cost for my `Production` subscription last month, filtered by the tag `CostCenter=Project-Alpha`, and grouped by `MeterSubcategory`?"

> **Multi-Subscription Query:**
> "Compare the costs for my `Staging` and `Production` subscriptions over the last 30 days."

#### Use Case: FinOps Waste & Savings Audit

> **Simple Audit:**
> "Run a finops audit on my `Production` subscription in `eastus`."

> **Multi-Region, Multi-Subscription Audit:**
> "Check for unused resources in `westus2` and `westeurope` for my `Prod-US` and `Prod-EU` subscriptions."

> **Comprehensive Audit for All Subscriptions:**
> "Run a FinOps audit for all my configured subscriptions in `eastus`."

### Supported Clients
- Claude Desktop
- Amazon Q CLI
- Any MCP-compatible client supporting tools 
> View the list of clients that support MCP Servers at <https://modelcontextprotocol.io/clients>

### Tool Reference

#### `get_cost`
Fetches cost and usage data from Azure Cost Management.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `profiles` | `List[str]` | A list of Azure subscription names or IDs to use. |
| `all_profiles` | `bool` | If `True`, use all available subscriptions. Defaults to `False`. |
| `time_range_days`| `int` | Number of past days to fetch data for (e.g., `7` for last 7 days). |
| `start_date_iso` | `str` | Start date in `YYYY-MM-DD` format. Takes precedence over `time_range_days`. |
| `end_date_iso` | `str` | End date in `YYYY-MM-DD` format. Must be used with `start_date_iso`. |
| `tags` | `List[str]` | Filter by cost allocation tags. Format: `["Key=Value", "Key2=Value2"]`. |
| `dimensions` | `List[str]` | Filter by dimensions. Format: `["REGION=us-east-1"]`. |
| `group_by` | `str` | The dimension to group costs by. Default is `ServiceName`. |

#### `run_finops_audit`
Runs a financial audit to find unused and potentially costly resources.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `regions` | `List[str]` | A list of Azure regions to run the audit in (e.g., `["eastus", "westeurope"]`). |
| `profiles` | `List[str]` | A list of Azure subscription names or IDs to use. |
| `all_profiles`| `bool` | If `True`, use all available profiles. Defaults to `False`. |

> **Output Format:** JSON, CSV, PDF, HTML, Markdown (depending on client capabilities)

### Cost Considerations

This tool interacts with the Azure Cost Management API. Azure charges for these API calls.
-   **Cost:** Every time you use `get_cost` tool, it makes 2 calls to the Cost Explorer API and it costs **$0.01**.
-   The `run_finops_audit` tool calls other Azure service APIs (Compute, Network, Consumption) which are generally included in the free tier or have negligible costs at typical usage levels.

### Development & Contributing

Contributions are welcome! If you'd like to improve the server or add new features, please follow these steps:

1.  **Fork and Clone:** Fork the repository and clone it to your local machine.
2.  **Set Up Environment with uv:**
    ```bash
    git clone https://github.com/your-username/azure-finops-mcp-server.git
    cd azure-finops-mcp-server
    uv venv
    source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
    ```
3.  **Install in Editable Mode with uv:**
    ```bash
    uv pip install -e .
    ```
4.  **Make Changes:** Add your features or bug fixes.
5.  **Submit a Pull Request:** Open a PR against the `main` branch with a clear description of your changes.

### License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for full details.

---

This is inspired by the AWS FinOps MCP Server project

Originally created by **Ravi Kiran** for AWS, migrated to Azure by **Juliano Barbosa**