Azure FinOps MCP Server

Azure FinOps MCP Server

LLM クライアント（Claude Desktop、Claude Code、VS Code、Cursor）から、複数のサブスクリプションにわたる Azure のコスト分析、予算管理、予測、リソース最適化を会話形式で利用できる MCP サーバーです。

ツール

検出

ツール	目的
list_subscriptions	使用可能なサブスクリプションをわかりやすい名前付きで一覧表示します

コスト分析

ツール	目的
get_cost_summary	指定期間の合計コスト（単一のサブスクリプション）
get_cost_by_dimension	サービス／RG／場所／メーター別のコスト内訳
get_cost_by_tag	タグ値ごとのコスト（ショーバック／チャージバック）
get_month_to_date_cost	当月の支出（単一のサブスクリプション）
get_portfolio_month_to_date_cost	すべてのサブスクリプションにわたる当月の支出

予算

ツール	目的
get_budget_status	単一のサブスクリプションの予算消化状況
get_portfolio_budget_status	すべてのサブスクリプションにわたる予算状況

最適化

ツール	目的
find_idle_resources	未接続のディスク、使用されていない IP／NIC、停止中の VM
find_idle_resources_portfolio	すべてのサブスクリプションにわたる未使用リソース
get_advisor_recommendations	年間削減額を含む Azure Advisor のコストに関する推奨事項
get_vm_utilization	適正なサイズへの変更を検証する CPU 統計

予測

ツール	目的
forecast_month_end_spend	月末コストの予測（単一のサブスクリプション）
forecast_portfolio_month_end_spend	すべてのサブスクリプションにわたる月末コストの予測

クイックインストール

pip install azure-finops-mcp

インストールしたコマンドを使って MCP クライアントの設定に追加します。リポジトリのクローンは不要です。

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

クライアントごとの設定ファイルの場所については、以下のクライアント設定セクションをご覧ください。

---

前提条件

• Python 3.11+
• Azure CLI がインストールされ、ログイン済みであること（az login）

Azure RBAC のアクセス許可

このサーバーを実行する ID（ユーザー、サービスプリンシパル、またはマネージド ID）には、クエリ対象とする各サブスクリプションで次の 3 つのロールが割り当てられている必要があります。

ロール	目的
Cost Management Reader	コスト分析、予測、予算クエリ
Reader	Resource Graph によるリソースのインベントリ
Monitoring Reader	Azure Monitor による VM の利用状況メトリック

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

AZURE_ALLOWED_SUBSCRIPTIONS に記載されている各サブスクリプションで繰り返します。

ローカル開発（自分のユーザー）

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

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

サブスクリプションの Owner または Contributor であれば、これらのロールはすでにユーザーに割り当てられています。 そうでない場合は、Azure 管理者に割り当てを依頼してください。

マネージド ID（Container Apps へのデプロイ）

deploy.sh でデプロイすると、スクリプトによって Container App のシステム割り当てマネージド ID に、許可された各サブスクリプションでこれら 3 つのロールが自動的に割り当てられます。 認証情報やシークレットは不要です。実行時に DefaultAzureCredential がマネージド ID を自動的に取得します。

インストール

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

.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

MCP Inspector でテストする

Inspector は、ツールを対話的に呼び出し、未加工の JSON-RPC メッセージを確認できる Web UI です。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

Inspector の UI で次の操作を行います。

1. Transport Type が STDIO であることを確認します
2. Connect をクリックします。接続に成功し、サーバー名として「azure-finops」が表示されます
3. Tools に移動して List Tools をクリックします。15 個すべてのツールが表示されます
4. まず list_subscriptions を試します（引数は不要です）
5. 次に get_month_to_date_cost を試します（引数は不要です。既定のサブスクリプションが使用されます）

クライアント設定

まず venv の Python の絶対パスを確認します。以下の各設定で必要になります。

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

---

Claude Desktop

claude_desktop_config.json を編集します。

OS	パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/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"
      }
    }
  }
}

Claude Desktop を再起動します。チャット入力欄にツールアイコンが表示されれば、サーバーが接続されています。

---

VS Code（GitHub Copilot／エージェントモード）

ワークスペースに .vscode/mcp.json を作成するか、ユーザーの settings.json の "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"
      }
    }
  }
}

VS Code 1.99 以降と GitHub Copilot 拡張機能が必要です。チャットパネルを開き、 Agent モードに切り替えると、azure-finops ツールが自動的に表示されます。

---

Cursor

~/.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"
      }
    }
  }
}

または、Cursor Settings → MCP → Add new global MCP server から追加します。 Cursor を再起動します。ツールは Cursor の Agent／Composer パネルに表示されます。

---

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

---

リモート HTTP（Azure Container Apps へのデプロイ後）

すべてのクライアントで、HTTP 経由でデプロイ済みサーバーに接続できます。ローカルの Python は不要です。

Claude Desktop／Cursor — 上記と同じ設定ファイルに追加します。

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

VS Code — .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

プロンプトの例

接続したら、次の例を試してください。

• 「許可されているサブスクリプションは何ですか？」
• 「すべてのサブスクリプションで、今月の累計支出はいくらですか？」
• 「先月、prod サブスクリプションで最も費用がかかったサービスを10個教えてください。」
• 「costcenter タグ別に、前四半期の支出を分類してください。」
• 「予算超過が近いものはありますか？」
• 「すべてのサブスクリプションで、アイドル状態のリソースを表示してください。」
• 「Azure Advisor はコスト削減のために何を推奨していますか？」
• 「VM my-analytics-vm は実際に使われていますか？過去14日間の CPU を確認してください。」
• 「今月の予測と予算を比較してください。」

アーキテクチャ

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

主な設計上の決定

柔軟なツールよりも、用途を絞ったツールを選びます。 LLM は、複雑なクエリオブジェクトを組み立てるよりも、わかりやすい名前のツールから選ぶほうがはるかに得意です。用途に特化した15個のツールは、設定可能な3個のツールより優れています。

サブスクリプションの許可リスト。 環境変数から読み込む frozenset です。すべてのツールが resolve_subscription() を呼び出し、リストにない ID は拒否します。これにより、LLM が許可されていないサブスクリプションをクエリするのを防ぎます。プロンプトインジェクション対策として重要です。

ポートフォリオツールはサブスクリプションごとのエラーを捕捉します。 5つ以上のサブスクリプションをクエリする場合、RBAC が異なっていたり、状態が不安定だったりするものがあるかもしれません。ポートフォリオツール（get_portfolio_*）はそれぞれのサブスクリプションを try/except で囲み、エラーを別途一覧表示したうえで、部分的な結果を返します。

キャッシュ対象は Cost Management のみです。 コストのクエリは負荷が高く、レート制限があります（テナントあたり約30 req/min）。コストデータの更新は、最短でも1時間ごとです。デフォルトの15分の TTL なら、新鮮さをほとんど損なわずに、レート制限への余裕を大きく確保できます。Resource Graph と Advisor は高速で低コストなため、キャッシュは不要です。

文章ではなく、構造化された戻り値。 ツールは、列・行・メタデータを含む dict を返します。LLM がそれを自然な文章で説明します。これにより、ツールの応答に英語を埋め込むこと（プロンプトの変更に弱くなります）を避けられます。

Azure へのデプロイ（リモートモード）

チーム全体で利用するには、リモート HTTP サーバーとしてデプロイします。

1. server.py でトランスポートを切り替えます。

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

2. Dockerfile：

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

3. ユーザー割り当てマネージド ID を使用して、Azure Container Apps にデプロイします。

4. 各サブスクリプションで、マネージド ID にRBAC ロールを付与します（同じ3つのロール：Cost Management Reader、 Reader、Monitoring Reader）。

5. APIM または Azure Front Door と Entra ID を使用して認証を追加します。 MCP はリモートサーバーでの OAuth をサポートしています。

6. DefaultAzureCredential がマネージド ID を自動的に検出します。 コードの変更は不要です。

トラブルシューティング

問題	解決方法
DefaultAzureCredential の認証エラー	az login を実行し、az account show で確認します
Cost Management の 429 スロットリング	FINOPS_CACHE_TTL_SECONDS を増やします
予算リストが空	予算はポータルで作成する必要があります。API では作成できません
find_idle_resources のエラー	サブスクリプションスコープで Reader RBAC が必要です
Inspector の「Connection Error」	Command フィールドで venv の python3 の絶対パスを指定します
print() がサーバーを壊す	MCP ツール内で print() を使用しないでください。stdio の JSON ストリームが壊れます。代わりに logging を使用してください