AKS-MCP
About
Enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters.
Details
- Author
- azure
- Categories
- Cloud Service, Other, Infrastructure
- Tags
- #azure, #kubernetes
Jump to
Setup
Install AKS-MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/azure/aks-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
- Operate (CRUD) AKS resources
- Retrieve details related to AKS clusters (VNets, Subnets, NSGs, Route Tables, etc.)
- Manage Azure Fleet operations for multi-cluster scenarios
Supported Deployment Model and Security Considerations
AKS-MCP is designed to be run locally, by a single trusted user, as a bridge between that user's own AI assistant and their own Azure/AKS resources.This is the only deployment model the project supports and hardens for.
AKS-MCP executes command-line tools — includingaz,kubectl,helm,cilium, andhubble—using the identity of the process it runs as. It does not perform per-caller authorization, and it does not attempt to sandbox the commands it runs. Therefore:
Anyone who can invoke AKS-MCP tools effectively has the full Azure and Kubernetes privileges of the identity AKS-MCP is running under.
This includes the ability to obtain reusable credentials. For example, inreadwriteoradminmode a caller can reach Azure Resource Manager and AKS with the server identity's full authority, andkubectlorhelmcan be used to read Secrets, mint service account tokens, or deploy arbitrary workloads into the cluster. This is an inherent consequence of exposing a CLI execution surface — it is not prevented by--access-level.
Specific credential-returning Azure CLI commands (such asaz account get-access-tokenandaz aks get-credentials) are rejected by an explicit denylist. That denylist reduces accidental exposure — it isnota security boundary, it does not cover thekubectl,helm,cilium, orhubblesurfaces, and it must not be relied upon to contain an untrusted caller.
Treat the ability to call AKS-MCP as equivalent to handing over a shell that is already logged in as the server identity.
Removing HTTP/SSE transports and the official remote deployment artifacts removes the supported network-reachable service and its remote-caller threat model. In the supported configuration, AKS-MCP has no listener that accepts requests from the network.
This doesnotmake the local MCP client, its prompts, or--access-levelan authorization boundary. A person or process that controls the local client, its server configuration, or AKS-MCP can normally run the same CLI commands under the same identity without AKS-MCP. Protecting the workstation, client configuration, and local credentials remains the operator's responsibility.
--access-level(readonly/readwrite/admin) is aguardrail to reduce accidental damagefrom an AI assistant that misinterprets a request. It isnota security boundary against a deliberately malicious caller, and it must not be relied upon to contain an untrusted party. Do not expose AKS-MCP to callers you would not grant the underlying Azure/Kubernetes credentials to directly.
- Run as a local subprocess, launched on demand by your local MCP client.
- Authenticate with your own developer identity viaaz login.
- Grant the identity only the Azure/Kubernetes permissions you actually need.
AKS-MCP supports only stdio and must be launched as a local subprocess by an MCP client. Do not expose it through HTTP, SSE, a container service, Helm, Kubernetes, a proxy, or a gateway. Any third-party bridge is outside the project's security and support boundary.
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): WhenAZURE_CLIENT_ID,AZURE_CLIENT_SECRET,AZURE_TENANT_IDenvironment 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): WhenAZURE_CLIENT_ID,AZURE_TENANT_ID,AZURE_FEDERATED_TOKEN_FILEenvironment 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 onlyAZURE_CLIENT_IDenvironment variable is present, a user-assigned managed identity login is performed using the following command:az login --identity -u CLIENT_ID
System-assigned Managed Identity: WhenAZURE_MANAGED_IDENTITYis set tosystem, 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, viaaz login) and uses the existing session.
- IfAZURE_SUBSCRIPTION_IDis set, AKS-MCP will runaz account set --subscription SUBSCRIPTION_IDafter login.
- The federated token file must be exactly/var/run/secrets/azure/tokens/azure-identity-tokenand is strictly validated; other paths are rejected.
- After each login, AKS-MCP verifies authentication withaz account show --query id -o tsv.
- Ensure the Azure CLI is installed and on PATH.
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_FEDERATED_TOKEN_FILE
- AZURE_SUBSCRIPTION_ID
- AZURE_MANAGED_IDENTITY(set tosystemto opt into system-assigned managed identity)
The AKS-MCP server provides consolidated tools for interacting with AKS clusters. By default, the server usesunified tools(call_azfor Azure operations andcall_kubectlfor Kubernetes operations) which provide a more flexible interface. For backward compatibility, you can enablelegacy specialized toolsby setting the environment variableUSE_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 theaccess levelparameter to your MCP configuration file:
- Navigate to yourmcp.jsonfile, or go to MCP: List Servers -> AKS-MCP -> Show Configuration Details in theCommand Palette(For VSCode;Ctrl+Shift+Pon Windows/Linux orCmd+Shift+Pon macOS).
- In the "args" section of AKS-MCP, add the following parameters: "--access-level", "readwrite" / "admin"
"args": [ "--access-level", "readwrite" ]
These tools have been designed to provide comprehensive functionality through unified interfaces:
Tool:call_az(default, available whenUSE_LEGACY_TOOLSis not set or set tofalse)
Unified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.
- 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)
{ "cli_command": "az aks list --resource-group myResourceGroup --output json" }
- readonly: Only read operations are allowed
- readwrite/admin: Both read and write operations are allowed
Important:Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).
Tool:az_aks_operations(available whenUSE_LEGACY_TOOLS=true)
Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.
- show: Show cluster details
- list: List clusters in subscription/resource group
- get-versions: Get available Kubernetes versions
- check-network: Perform outbound network connectivity check
- nodepool-list: List node pools in cluster
- nodepool-show: Show node pool details
- account-list: List Azure subscriptions
Read-Write(readwrite/adminaccess levels):
- create: Create new cluster
- delete: Delete cluster
- scale: Scale cluster node count
- start: Start a stopped cluster
- stop: Stop a running cluster
- update: Update cluster configuration
- upgrade: Upgrade Kubernetes version
- nodepool-add: Add node pool to cluster
- nodepool-delete: Delete node pool
- nodepool-scale: Scale node pool
- nodepool-upgrade: Upgrade node pool
- account-set: Set active subscription
- login: Azure authentication
- get-credentials: Get cluster credentials for kubectl access
Unified tool for getting Azure network resource information used by AKS clusters.
- all: Get information about all network resources
- vnet: Virtual Network information
- subnet: Subnet information
- nsg: Network Security Group information
- route_table: Route Table information
- load_balancer: Load Balancer information
- private_endpoint: Private endpoint information
Unified tool for Azure monitoring and diagnostics operations for AKS clusters.
- metrics: List metric values for resources
- resource_health: Retrieve resource health events for AKS clusters
- app_insights: Execute KQL queries against Application Insights telemetry data
- diagnostics: Check if AKS cluster has diagnostic settings configured
- control_plane_logs: Query AKS control plane logs with safety constraints and time range validation
- Get detailed VMSS configuration for node pools in the AKS cluster
Collect system logs from AKS VMSS nodes for debugging and troubleshooting.
- aks_resource_id: AKS cluster resource ID
- vmss_name: VMSS name (obtain fromget_aks_vmss_infoorkubectl get nodes)
- instance_id: VMSS instance ID
- log_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 overlines
- level: Log level filter (ERROR,WARN,INFO)
- filter: Filter logs by keyword (case-insensitive text match)
{ "aks_resource_id": "/subscriptions/.../managedClusters/myAKS", "vmss_name": "aks-nodepool1-12345678-vmss", "instance_id": "0", "log_type": "kubelet", "since": "1h", "level": "ERROR", "filter": "ImagePullBackOff" }
- Only supports Linux VMSS nodes (Windows nodes and standalone VMs are not supported yet)
- Only one run command can execute at a time per VMSS instance
Unified tool for managing Azure Virtual Machines (VMs) and Virtual Machine Scale Sets (VMSS) used by AKS.
- show: Get details of a VM/VMSS
- list: List VMs/VMSS in subscription or resource group
- get-instance-view: Get runtime status
- start: Start VM
- stop: Stop VM
- restart: Restart VM/VMSS instances
- reimage: Reimage VMSS instances (VM not supported for reimage)
Resource Types:vm(single virtual machines),vmss(virtual machine scale sets)
Comprehensive Azure Fleet management for multi-cluster scenarios.
- Fleet Operations: list, show, create, update, delete, get-credentials
- Member Operations: list, show, create, update, delete
- Update Run Operations: list, show, create, start, stop, delete
- Update Strategy Operations: list, show, create, delete
- ClusterResourcePlacement Operations: list, show, get, create, delete
Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement CRD operations.
Unified tool for executing AKS diagnostic detector operations.
- list: List all available AKS cluster detectors
- run: Run a specific AKS diagnostic detector
- run_by_category: Run all detectors in a specific category
- operation(required): Operation to perform (list,run, orrun_by_category)
- aks_resource_id(required): AKS cluster resource ID
- detector_name(required forrunoperation): Name of the detector to run
- category(required forrun_by_categoryoperation): Detector category
- start_time(required forrunandrun_by_categoryoperations): Start time in UTC ISO format (within last 30 days)
- end_time(required forrunandrun_by_categoryoperations): End time in UTC ISO format (within last 30 days, max 24h from start)
- Best Practices
- Cluster and Control Plane Availability and Performance
- Connectivity Issues
- Create, Upgrade, Delete and Scale
- Deprecations
- Identity and Security
- Node Health
- Storage
{ "operation": "list", "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx" }
{ "operation": "run", "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx", "detector_name": "node-health-detector", "start_time": "2025-01-15T10:00:00Z", "end_time": "2025-01-15T12:00:00Z" }
Retrieve and manage Azure Advisor recommendations for AKS clusters.
- list: List recommendations with filtering options
- report: Generate recommendation reports
- Filter Options: resource_group, cluster_names, category (Cost, HighAvailability, Performance, Security), severity (High, Medium, Low)
Note: All Kubernetes tools (kubectl, helm, cilium, hubble) are enabled by default. Use--enabled-componentsto selectively enable specific components.
Tool:call_kubectl(default, available whenUSE_LEGACY_TOOLSis not set or set tofalse)
Unified tool for executing kubectl commands directly. This tool provides a flexible interface to run anykubectlcommand with full argument support.
- args: The kubectl command arguments (e.g.,get pods,describe node mynode,apply -f deployment.yaml)
{ "args": "get pods -n kube-system -o wide" }
Access Control:Operations are restricted based on the configured access level:
- readonly: Only read operations (get, describe, logs, etc.) are allowed
- readwrite/admin: All operations including mutating commands (create, delete, apply, etc.)
- kubectl_resources: View resources (get, describe) - filtered to read-only operations in readonly mode
- kubectl_diagnostics: Debug and diagnose (logs, events, top, exec, cp)
- kubectl_cluster: Cluster information (cluster-info, api-resources, api-versions, explain)
- kubectl_config: Configuration management (diff, auth, config) - filtered to read-only operations in readonly mode
Read-Write/Admin(readwrite/adminaccess levels):
- kubectl_resources: Full resource management (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
- kubectl_workloads: Workload lifecycle (run, expose, scale, autoscale, rollout)
- kubectl_metadata: Metadata management (label, annotate, set)
- kubectl_config: Full configuration management (diff, auth, certificate, config)
Cilium CLI for eBPF-based networking and security.
Hubble network observability for Cilium.
Real-time observability tool for Azure Kubernetes Service (AKS) clusters using eBPF.
- deploy: Deploy Inspektor Gadget to the cluster (via the AKS cluster extension)
- undeploy: Remove the Inspektor Gadget cluster extension from the cluster
- is_deployed: Check deployment status
- run: Run one-shot gadgets
- start: Start continuous gadgets
- stop: Stop running gadgets
- get_results: Retrieve gadget results
- list_gadgets: List available gadgets
- observe_dns: Monitor DNS requests and responses
- observe_tcp: Monitor TCP connections
- observe_file_open: Monitor file system operations
- observe_process_execution: Monitor process execution
- observe_signal: Monitor signal delivery
- observe_system_calls: Monitor system calls
- top_file: Top files by I/O operations
- top_tcp: Top TCP connections by traffic
- tcpdump: Capture network packets
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
