Labsco
Azure logo

AKS-MCP

✓ Official★ 134

from Azure

Enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters.

🔥🔥🔥🔥✓ VerifiedPaid serviceNeeds API keys
#email#automation#cloud#devops#git#search#maps#security

AKS-MCP

SafeSkill 92/100 The 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:

  • Operate (CRUD) AKS resources
  • Retrieve details related to AKS clusters (VNets, Subnets, NSGs, Route Tables, etc.)
  • Manage Azure Fleet operations for multi-cluster scenarios

How it works

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.

Azure CLI Authentication

AKS-MCP uses Azure CLI (az) for AKS operations. Azure CLI authentication is attempted in this order:

  1. 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

  2. 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

  3. User-assigned Managed Identity (managed identity client ID): When only AZURE_CLIENT_ID environment variable is present, a user-assigned managed identity login is performed using the following command: az login --identity -u CLIENT_ID

  4. System-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

  5. 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:

  • If AZURE_SUBSCRIPTION_ID is set, AKS-MCP will run az account set --subscription SUBSCRIPTION_ID after login.

Notes and security:

  • The federated token file must be exactly /var/run/secrets/azure/tokens/azure-identity-token and is strictly validated; other paths are rejected.
  • After each login, AKS-MCP verifies authentication with az account show --query id -o tsv.
  • Ensure the Azure CLI is installed and on PATH.

Environment variables used:

  • AZURE_TENANT_ID
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_FEDERATED_TOKEN_FILE
  • AZURE_SUBSCRIPTION_ID
  • AZURE_MANAGED_IDENTITY (set to system to opt into system-assigned managed identity)

Available Tools

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:

  1. Navigate to your mcp.json file, or go to MCP: List Servers -> AKS-MCP -> Show Configuration Details in the Command Palette (For VSCode; Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
  2. In the "args" section of AKS-MCP, add the following parameters: "--access-level", "readwrite" / "admin"

For example:

Copy & paste — that's it
"args": [
  "--transport",
  "stdio",
  "--access-level",
  "readwrite"
]

These tools have been designed to provide comprehensive functionality through unified interfaces:

<details> <summary>Azure CLI Operations (Unified Tool)</summary>

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:

Copy & paste — that's it
{
  "cli_command": "az aks list --resource-group myResourceGroup --output json"
}

Access Control:

  • 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 (;).

</details> <details> <summary>AKS Cluster Management (Legacy Tool)</summary>

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 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/admin access 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

  • Admin-Only (admin access level):

    • get-credentials: Get cluster credentials for kubectl access
</details> <details> <summary>Network Resource Management</summary>

Tool: aks_network_resources

Unified tool for getting Azure network resource information used by AKS clusters.

Available Resource Types:

  • 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
</details> <details> <summary>Monitoring and Diagnostics</summary>

Tool: aks_monitoring

Unified tool for Azure monitoring and diagnostics operations for AKS clusters.

Available Operations:

  • 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
</details> <details> <summary>Compute Resources</summary>

Tool: get_aks_vmss_info

  • Get detailed VMSS configuration for node pools in the AKS cluster

Tool: collect_aks_node_logs

Collect system logs from AKS VMSS nodes for debugging and troubleshooting.

Parameters:

  • aks_resource_id: AKS cluster resource ID
  • vmss_name: VMSS name (obtain from get_aks_vmss_info or kubectl 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 over lines
  • level: Log level filter (ERROR, WARN, INFO)
  • filter: Filter logs by keyword (case-insensitive text match)

Example Usage:

Copy & paste — that's it
{
  "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:

  • 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

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/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)

</details> <details> <summary>Fleet Management</summary>

Tool: az_fleet

Comprehensive Azure Fleet management for multi-cluster scenarios.

Available Operations:

  • 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.

</details> <details> <summary>Diagnostic Detectors</summary>

Tool: aks_detector

Unified tool for executing AKS diagnostic detector operations.

Available 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

Parameters:

  • operation (required): Operation to perform (list, run, or run_by_category)
  • aks_resource_id (required): AKS cluster resource ID
  • detector_name (required for run operation): Name of the detector to run
  • category (required for run_by_category operation): Detector category
  • start_time (required for run and run_by_category operations): Start time in UTC ISO format (within last 30 days)
  • end_time (required for run and run_by_category operations): End time in UTC ISO format (within last 30 days, max 24h from start)

Available Categories:

  • Best Practices
  • Cluster and Control Plane Availability and Performance
  • Connectivity Issues
  • Create, Upgrade, Delete and Scale
  • Deprecations
  • Identity and Security
  • Node Health
  • Storage

Example Usage:

Copy & paste — that's it
{
  "operation": "list",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
}
Copy & paste — that's it
{
  "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"
}
</details> <details> <summary>Azure Advisor</summary>

Tool: aks_advisor_recommendation

Retrieve and manage Azure Advisor recommendations for AKS clusters.

Available Operations:

  • 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)
</details> <details> <summary>Kubernetes Operations</summary>

Note: All Kubernetes tools (kubectl, helm, cilium, hubble) are enabled by default. Use --enabled-components to selectively enable specific components.

Unified kubectl Tool (Default)

Tool: call_kubectl (default, available when USE_LEGACY_TOOLS is not set or set to false)

Unified tool for executing kubectl commands directly. This tool provides a flexible interface to run any kubectl command with full argument support.

Parameters:

  • args: The kubectl command arguments (e.g., get pods, describe node mynode, apply -f deployment.yaml)

Example Usage:

Copy & paste — that's it
{
  "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.)

Legacy kubectl Tools (Specialized)

Available when USE_LEGACY_TOOLS=true:

  • Read-Only (all access levels):

    • 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/admin access 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)

Helm

Tool: call_helm

Helm package manager for Kubernetes.

Cilium

Tool: call_cilium

Cilium CLI for eBPF-based networking and security.

Hubble

Tool: call_hubble

Hubble network observability for Cilium.

</details> <details> <summary>Real-time Observability</summary>

Tool: inspektor_gadget_observability

Real-time observability tool for Azure Kubernetes Service (AKS) clusters using eBPF.

Available Actions:

  • deploy: Deploy Inspektor Gadget to cluster
  • undeploy: Remove Inspektor Gadget from 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

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
</details>

Development

Prerequisites

  • Go ≥ 1.24.x installed on your local machine
  • Bash available as /usr/bin/env bash (Makefile targets use multi-line recipes with fail-fast mode)
  • GNU Make 4.x or later
  • Docker (optional, for container builds and testing)

Note: If your login shell is different (e.g., zsh on macOS), you do not need to change it — the Makefile sets variables to run all recipes in bash for consistent behavior across platforms.

Building from Source

This project includes a Makefile for convenient development, building, and testing. To see all available targets:

Copy & paste — that's it
make help

Quick Start

Copy & paste — that's it
# Build the binary
make build

# Run tests
make test

# Run tests with coverage
make test-coverage

# Format and lint code
make check

# Build for all platforms
make release

Common Development Tasks

Copy & paste — that's it
# Install dependencies
make deps

# Build and run with --help
make run

# Clean build artifacts
make clean

# Install binary to GOBIN
make install

Docker

Copy & paste — that's it
# Build Docker image
make docker-build

# Run Docker container
make docker-run

Manual Build

If you prefer to build without the Makefile:

Copy & paste — that's it
go build -o aks-mcp ./cmd/aks-mcp

Telemetry

Telemetry collection is on by default.

To opt out, set the environment variable AKS_MCP_COLLECT_TELEMETRY=false.

Contributing

We welcome contributions to AKS-MCP! Whether you're fixing bugs, adding features, or improving documentation, your help makes this project better.

📖 Read our detailed Contributing Guide for comprehensive information on:

  • Setting up your development environment
  • Running AKS-MCP locally and testing with AI agents
  • Understanding the codebase architecture
  • Adding new MCP tools and features
  • Testing guidelines and best practices
  • Submitting pull requests

Quick Start for Contributors

  1. Prerequisites: Go ≥ 1.24.x, Azure CLI, Git
  2. Setup: Fork the repo, clone locally, run make deps && make build
  3. Test: Run make test and make check
  4. Develop: Follow the component-based architecture in CONTRIBUTING.md

Contributor License Agreement

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.