aks

AKS-MCP is a bridge that lets AI assistants issue commands to manage and inspect Azure Kubernetes Service (AKS) resources. It exposes consolidated tools for interacting with AKS clusters and related Azure networking resources, using a unified interface that translates natural language requests into Azure CLI or Kubernetes actions. By default, it uses unified tools to run Azure CLI commands (call_az) and Kubernetes operations (call_kubectl). When needed for backward compatibility, you can enable legacy specialized tools by setting USE_LEGACY_TOOLS=true. The server supports operations like listing clusters, creating or updating clusters, managing node pools, inspecting VNets, NSGs, and route tables, and collecting monitoring or diagnostic data. Your AI assistant can perform CRUD operations on AKS resources, retrieve cluster details, or fetch networking and monitoring information, with access controls to restrict actions as needed. To control permissions, you can configure read-only, read-write, or admin-level access per command in your MCP configuration.

Prerequisites:

• Python environment or uv tooling as required by your deployment (per MCP server setup)
• Access to an Azure subscription and proper Azure credentials configured via environment variables or appropriate authentication flow
• Azure CLI installed and on PATH, if using Azure CLI-based workflows

Step 1: Prepare environment

• Install Python and enable your virtual environment if desired
• Ensure internet access to fetch MCP server dependencies

Step 2: Install or run the MCP server package

• If using uvx (Python) as the launcher, ensure the package azure-aks-mcp is published and accessible
• Example (adjust to your package management workflow):
  • pipx install azure-aks-mcp
  • or uvx azure-aks-mcp

Step 3: Configure environment variables

• Set up authentication details for Azure as described in the README:
  • AZURE_TENANT_ID
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_FEDERATED_TOKEN_FILE (if using workload identity)
  • AZURE_SUBSCRIPTION_ID (optional)
  • AZURE_MANAGED_IDENTITY (optional, set to system)
  • USE_LEGACY_TOOLS (optional)

Step 4: Run the MCP server

• If using uvx, run a command like: uvx azure-aks-mcp
• Or run via your chosen orchestrator with the appropriate command and arguments as described in mcp_config

Step 5: Verify operation

• Ensure the server starts and logs show it connected to Azure and exposing the MCP endpoints
• Test with an MCP client by invoking available tools (call_az, aks_network_resources, aks_monitoring, etc.) through the unified interface

Tips and common issues:

• Ensure the federated token path (/var/run/secrets/azure/tokens/azure-identity-token) is accessible and validated if using workload identity, as other paths are rejected by AKS-MCP.
• If you encounter authentication failures, verify all required AZURE_* variables are set correctly and that Azure CLI login has not expired.
• When enabling legacy tools, be mindful of the permissions required by each operation; some commands may require admin or readwrite access.
• For network-related operations, ensure your environment has network egress access to Azure endpoints and that the AKS cluster allows the operations from your session.
• Use the optional AZURE_SUBSCRIPTION_ID to scope commands to a specific subscription after login.
• If you plan to run multiple clusters or multi-cluster scenarios, explore the Azure Fleet management capabilities described in the README to coordinate actions across clusters.