py-az-mcp

Azure MCP Server

A Model Context Protocol (MCP) server implementation that provides programmatic access to Azure Cloud resources through Azure CLI commands. This server enables seamless integration with Azure services and supports a wide range of Azure operations.

Features

Authentication

• Service Principal authentication support
• Automatic token management
• Environment variable configuration

Supported Azure Operations

Compute

• Virtual Machines (list, show, start, stop, delete, restart)
• Virtual Machine Scale Sets (list, scale, update)
• Azure Kubernetes Service (list clusters)

Storage

• Storage Accounts (list, show, create, delete)
• Storage Containers (list, create, delete)

App Services

• Web Apps (list, show, create, delete, start, stop, restart)
• Function Apps (list, show, delete, start, stop, restart)
• Deployment management

Networking

• Virtual Networks (list)
• Network Security Groups (list)
• Public IP Addresses (list)

Database

• SQL Servers (list)
• Cosmos DB Accounts (list)

Security

• Key Vaults (list, create, delete)
• Secrets Management (list, set, delete)
• Managed Identities (list)

Container Registry

• Registry Management (list, create, delete, update)
• Repository Management (list)

Resource Management

• Resource Groups (list, show, create, delete)
• Role Assignments (list, create, delete)
• Role Definitions (list)
• Subscription Management (list, show)

Prerequisites

• Python 3.13 or higher
• Azure CLI installed and configured
• Azure subscription and appropriate permissions
• Service Principal with required access

Installation

1. Clone the repository:

git clone <repository-url>
cd py-az-mcp

2. Install dependencies using uv:

uv pip sync

Or install directly from pyproject.toml:

uv pip install -e .

Configuration

1. Create a Service Principal and configure environment variables by running the utility script:

python create_service_principal.py

This script will:

• Authenticate you with Azure interactively
• Create a new Service Principal with Contributor role
• Automatically generate a .env file with the required credentials:
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_TENANT_ID
  • AZURE_SUBSCRIPTION_ID

Note: The .env file is automatically excluded from git tracking for security purposes.

Claude Desktop Configuration

To use this MCP server with Claude Desktop, configure the following:

1. Create or update the Claude Desktop configuration file:

{
  "mcpServers": {
    "Azure": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/your-path-to/py-az-mcp/server-azure.py"
      ]
    }
  }
}

The configuration file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Replace YOUR_USERNAME with your actual system username in both paths.

3. Ensure your virtual environment is properly set up:

cd /Users/YOUR_USERNAME/Source/Code/py-az-mcp
python -m venv .venv
source .venv/bin/activate
pip install mcp[cli]

4. Verify the configuration:
   • Open Claude Desktop
   • Click on the settings icon (⚙️)
   • Navigate to the "MCP Servers" section
   • The Azure server should be listed and enabled

Note: The server will start automatically when needed by Claude Desktop. Ensure all environment variables from the .env file are properly configured before using Azure commands through Claude.

Usage

1. Start the MCP server:

uv run --with mcp[cli] mcp run server-azure.py

2. The server will be available at http://127.0.0.1:6274

Example API Calls

List all subscriptions:

curl -X POST http://127.0.0.1:6274/tool/azure-cli -H "Content-Type: application/json" -d '{"command": "account list --output json"}'

List all resource groups:

curl -X POST http://127.0.0.1:6274/tool/azure-cli -H "Content-Type: application/json" -d '{"command": "group list --output json"}'

Dependencies

• Python >= 3.13
• mcp[cli] >= 1.6.0
• python-dotenv >= 1.0.0
• asyncio >= 3.4.3
• Azure CLI >= 2.57.0 (system requirement)

Project Structure

• server-azure.py: Main MCP server implementation with Azure CLI integration
• create_service_principal.py: Utility script for creating Azure Service Principal
• main.py: Package entry point (placeholder)
• pyproject.toml: Project dependencies and configuration
• .env: Environment variables configuration (not tracked in git)
• .python-version: Python version requirement

Error Handling

The server includes comprehensive error handling:

• JSON validation for all responses
• Azure CLI error capture and formatting
• Authentication error handling
• Parameter validation

Security Considerations

• Uses Service Principal authentication
• Supports environment variable configuration for sensitive data
• Implements proper error handling to prevent information disclosure
• Validates all input parameters

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.