by Azure
A Model Context Protocol (MCP) server that enables AI assistants to interact with AKS clusters. It serves as a bridge between AI tools (like Claude, Cursor, and GitHub Copilot) and AKS.
# Add to your Claude Code skills
git clone https://github.com/Azure/aks-mcpThe AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge between AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI assistants) and AKS, translating natural language requests into AKS operations and returning the results in a format the AI tools can understand.
It allows AI tools to:
AKS-MCP connects to Azure using the Azure SDK and provides a set of tools that AI assistants can use to interact with AKS resources. It leverages the Model Context Protocol (MCP) to facilitate this communication, enabling AI tools to make API calls to Azure and interpret the responses.
AKS-MCP uses Azure CLI (az) for AKS operations. Azure CLI authentication is attempted in this order:
Service Principal (client secret): When AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID environment variables are present, a service principal login is performed using the following command: az login --service-principal -u CLIENT_ID -p CLIENT_SECRET --tenant TENANT_ID
Workload Identity (federated token): When AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE environment variables are present, a federated token login is performed using the following command: az login --service-principal -u CLIENT_ID --tenant TENANT_ID --federated-token TOKEN
User-assigned Managed Identity (managed identity client ID): When only environment variable is present, a user-assigned managed identity login is performed using the following command:
No comments yet. Be the first to share your thoughts!
AZURE_CLIENT_IDaz login --identity -u CLIENT_IDSystem-assigned Managed Identity: When AZURE_MANAGED_IDENTITY is set to system, a system-assigned managed identity login is performed using the following command: az login --identity
Existing Login: When none of the above environment variables are set, AKS-MCP assumes you have already authenticated (for example, via az login) and uses the existing session.
Optional subscription selection:
AZURE_SUBSCRIPTION_ID is set, AKS-MCP will run az account set --subscription SUBSCRIPTION_ID after login.Notes and security:
/var/run/secrets/azure/tokens/azure-identity-token and is strictly validated; other paths are rejected.az account show --query id -o tsv.Environment variables used:
AZURE_TENANT_IDAZURE_CLIENT_IDAZURE_CLIENT_SECRETAZURE_FEDERATED_TOKEN_FILEAZURE_SUBSCRIPTION_IDAZURE_MANAGED_IDENTITY (set to system to opt into system-assigned managed identity)The AKS-MCP server provides consolidated tools for interacting with AKS
clusters. By default, the server uses unified tools (call_az for Azure operations and call_kubectl for Kubernetes operations) which provide a more flexible interface. For backward compatibility, you can enable legacy specialized tools by setting the environment variable USE_LEGACY_TOOLS=true.
Some tools will require read-write or admin permissions to run debugging pods on your cluster. To enable read-write or admin permissions for the AKS-MCP server, add the access level parameter to your MCP configuration file:
Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).For example:
"args": [
"--transport",
"stdio",
"--access-level",
"readwrite"
]
These tools have been designed to provide comprehensive functionality through unified interfaces:
Tool: call_az (default, available when USE_LEGACY_TOOLS is not set or set to false)
Unified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.
Parameters:
cli_command: The complete Azure CLI command to execute (e.g., az aks list --resource-group myRG, az vm list --subscription <sub-id>)timeout: Optional timeout in seconds (default: 120)Example Usage:
{
"cli_command": "az aks list --resource-group myResourceGroup --output json"
}
Access Control:
Important: Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).
Tool: az_aks_operations (available when USE_LEGACY_TOOLS=true)
Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.
Available Operations:
Read-Only (all access levels):
show: Show cluster detailslist: List clusters in subscription/resource groupget-versions: Get available Kubernetes versionscheck-network: Perform outbound network connectivity checknodepool-list: List node pools in clusternodepool-show: Show node pool detailsaccount-list: List Azure subscriptionsRead-Write (readwrite/admin access levels):
create: Create new clusterdelete: Delete clusterscale: Scale cluster node countstart: Start a stopped clusterstop: Stop a running clusterupdate: Update cluster configurationupgrade: Upgrade Kubernetes versionnodepool-add: Add node pool to clusternodepool-delete: Delete node poolnodepool-scale: Scale node poolnodepool-upgrade: Upgrade node poolaccount-set: Set active subscriptionlogin: Azure authenticationAdmin-Only (admin access level):
get-credentials: Get cluster credentials for kubectl accessTool: aks_network_resources
Unified tool for getting Azure network resource information used by AKS clusters.
Available Resource Types:
all: Get information about all network resourcesvnet: Virtual Network informationsubnet: Subnet informationnsg: Network Security Group informationroute_table: Route Table informationload_balancer: Load Balancer informationprivate_endpoint: Private endpoint informationTool: aks_monitoring
Unified tool for Azure monitoring and diagnostics operations for AKS clusters.
Available Operations:
metrics: List metric values for resourcesresource_health: Retrieve resource health events for AKS clustersapp_insights: Execute KQL queries against Application Insights telemetry datadiagnostics: Check if AKS cluster has diagnostic settings configuredcontrol_plane_logs: Query AKS control plane logs with safety constraints
and time range validationTool: get_aks_vmss_info
Tool: collect_aks_node_logs
Collect system logs from AKS VMSS nodes for debugging and troubleshooting.
Parameters:
aks_resource_id: AKS cluster resource IDvmss_name: VMSS name (obtain from get_aks_vmss_info or kubectl get nodes)instance_id: VMSS instance IDlog_type: Type of logs to collect (kubelet, containerd, kernel, syslog)lines: Number of recent log lines to return (default: 500, max: 2000)since: Time range for logs (e.g., 1h, 30m, 2d) - takes precedence over lineslevel: Log level filter (ERROR, WARN, INFO)filter: Filter logs by keyword (case-insensitive text match)Example Usage:
{
"aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
"vmss_name": "aks-nodepool1-12345678-vmss",
"instance_id": "0",
"log_type": "kubelet",
"since": "1h",
"level": "ERROR",
"filter": "ImagePullBackOff"
}
Limitations:
Tool: az_compute_operations
Unified tool for managing Azure Virtual Machines (VMs) and Virtual Machine Scale Sets (VMSS) used by AKS.
Available Operations:
show: Get details of a VM/VMSSlist: List VMs/VMSS in subscription or resource groupget-instance-view: Get runtime statusstart: Start VMstop: Stop VMrestart: Restart VM/VMSS instancesreimage: Reimage VMSS instances (VM not supported for reimage)Resource Types: vm (single virtual machines), vmss (virtual machine scale sets)
Tool: az_fleet
Comprehensive Azure Fleet management for multi-cluster scenarios.
Available Operations:
Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement CRD operations.
Tool: aks_detector
Unified tool for executing AKS diagnostic detector operations.
Available Operations: