{"id":"6c794f2f-2a11-4481-9ec4-38105721c676","slug":"aks-mcp","kind":"mcp","name":"aks-mcp","summary":"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.","owner":"Azure","repoUrl":"https://github.com/Azure/aks-mcp","license":"MIT","licenseTier":"permissive","trust":"official","stars":142,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-04-25T01:22:07.000Z","addedAt":"2026-10-14T03:44:05.544Z","logoUrl":"https://avatars.githubusercontent.com/u/6844498?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge","developer-tools"],"tags":["kubernetes"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-15T02:24:34.603Z","sample":false,"url":"https://conduits.dev/tools/aks-mcp","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# AKS-MCP\n\n[](https://safeskill.dev/scan/azure-aks-mcp)\nThe AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants\nto interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge\nbetween AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI\nassistants) and AKS, translating natural language requests into AKS operations\nand returning the results in a format the AI tools can understand.\n\nIt allows AI tools to:\n\n- Operate (CRUD) AKS resources\n- Retrieve details related to AKS clusters (VNets, Subnets, NSGs, Route Tables, etc.)\n- Manage Azure Fleet operations for multi-cluster scenarios\n\n## Supported Deployment Model and Security Considerations\n\n**AKS-MCP is designed to be run locally, by a single trusted user, as a bridge\nbetween that user's own AI assistant and their own Azure/AKS resources.** This\nis the only deployment model the project supports and hardens for.\n\n### The trust boundary\n\nAKS-MCP executes command-line tools — including `az`, `kubectl`, `helm`,\n`cilium`, and `hubble` — **using the identity of the process it runs as**. It\ndoes not perform per-caller authorization, and it does not attempt to sandbox\nthe commands it runs. Therefore:\n\n> **Anyone who can invoke AKS-MCP tools effectively has the full Azure and\n> Kubernetes privileges of the identity AKS-MCP is running under.**\n\nThis includes the ability to obtain reusable credentials. For example, in\n`readwrite` or `admin` mode a caller can reach Azure Resource Manager and AKS\nwith the server identity's full authority, and `kubectl` or `helm` can be used\nto read Secrets, mint service account tokens, or deploy arbitrary workloads\ninto the cluster. This is an inherent consequence of exposing a CLI execution\nsurface — it is not prevented by `--access-level`.\n\nSpecific credential-returning Azure CLI commands (such as\n`az account get-access-token` and `az aks get-credentials`) are rejected by an\nexplicit denylist. That denylist reduces accidental exposure — it is **not** a\nsecurity boundary, it does not cover the `kubectl`, `helm`, `cilium`, or\n`hubble` surfaces, and it must not be relied upon to contain an untrusted\ncaller.\n\n**Treat the ability to call AKS-MCP as equivalent to handing over a shell that\nis already logged in as the server identity.**\n\n### Network exposure and local authority\n\nRemoving HTTP/SSE transports and the official remote deployment artifacts\nremoves the supported network-reachable service and its remote-caller threat\nmodel. In the supported configuration, AKS-MCP has no listener that accepts\nrequests from the network.\n\nThis does **not** make the local MCP client, its prompts, or `--access-level`\nan authorization boundary. A person or process that controls the local client,\nits server configuration, or AKS-MCP can normally run the same CLI commands\nunder the same identity without AKS-MCP. Protecting the workstation, client\nconfiguration, and local credentials remains the operator's responsibility.\n\n### What `--access-level` is and is not\n\n`--access-level` (`readonly` / `readwrite` / `admin`) is a **guardrail to reduce\naccidental damage** from an AI assistant that misinterprets a request. It is\n**not** a security boundary against a deliberately malicious caller, and it must\nnot be relied upon to contain an untrusted party. Do not expose AKS-MCP to\ncallers you would not grant the underlying Azure/Kubernetes credentials to\ndirectly.\n\n### Recommended (supported) setup\n\n- Run as a local subprocess, launched on demand by your local MCP client.\n- Authenticate with your own developer identity via `az login`.\n- Grant the identity only the Azure/Kubernetes permissions you actually need.\n\n### Unsupported deployment models\n\nAKS-MCP supports only stdio and must be launched as a local subprocess by an\nMCP client. Do not expose it through HTTP, SSE, a container service, Helm,\nKubernetes, a proxy, or a gateway. Any third-party bridge is outside the\nproject's security and support boundary.\n\n## How it works\n\nAKS-MCP connects to Azure using the Azure SDK and provides a set of tools that\nAI assistants can use to interact with AKS resources. It leverages the Model\nContext Protocol (MCP) to facilitate this communication, enabling AI tools to\nmake API calls to Azure and interpret the responses.\n\n## Azure CLI Authentication\n\nAKS-MCP uses Azure CLI (az) for AKS operations. Azure CLI authentication is attempted in this order:\n\n1. 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`\n\n1. 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`\n\n1. 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`\n\n1. 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`\n\n1. 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.\n\nOptional subscription selection:\n\n- If `AZURE_SUBSCRIPTION_ID` is set, AKS-MCP will run `az account set --subscription SUBSCRIPTION_ID` after login.\n\nNotes and security:\n\n- The federated token file must be exactly `/var/run/secrets/azure/tokens/azure-identity-token` and is strictly validated; other paths are rejected.\n- After each login, AKS-MCP verifies authentication with `az account show --query id -o tsv`.\n- Ensure the Azure CLI is installed and on PATH.\n\nEnvironment variables used:\n\n- `AZURE_TENANT_ID`\n- `AZURE_CLIENT_ID`\n- `AZURE_CLIENT_SECRET`\n- `AZURE_FEDERATED_TOKEN_FILE`\n- `AZURE_SUBSCRIPTION_ID`\n- `AZURE_MANAGED_IDENTITY` (set to `system` to opt into system-assigned managed identity)\n\n## Available Tools\n\nThe AKS-MCP server provides consolidated tools for interacting with AKS\nclusters. 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`.\n\nSome 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:\n\n1. 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).\n2. In the \"args\" section of AKS-MCP, add the following parameters: \"--access-level\", \"readwrite\" / \"admin\"\n\nFor example:\n```\n\"args\": [\n \"--access-level\",\n \"readwrite\"\n]\n```\n\nThese tools have been designed to provide comprehensive functionality\nthrough unified interfaces:\n\n\nAzure CLI Operations (Unified Tool)
\n\n**Tool:** `call_az` *(default, available when `USE_LEGACY_TOOLS` is not set or set to `false`)*\n\nUnified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.\n\n**Parameters:**\n- `cli_command`: The complete Azure CLI command to execute (e.g., `az aks list --resource-group myRG`, `az vm list --subscription `)\n- `timeout`: Optional timeout in seconds (default: 120)\n\n**Example Usage:**\n```json\n{\n \"cli_command\": \"az aks list --resource-group myResourceGroup --output json\"\n}\n```\n\n**Access Control:**\n- **readonly**: Only read operations are allowed\n- **readwrite/admin**: Both read and write operations are allowed\n\n**Important:** Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).\n\n \n\n\nAKS Cluster Management (Legacy Tool)
\n\n**Tool:** `az_aks_operations` *(available when `USE_LEGACY_TOOLS=true`)*\n\nUnified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.\n\n**Available Operations:**\n\n- **Read-Only** (all access levels):\n - `show`: Show cluster details\n - `list`: List clusters in subscription/resource group\n - `get-versions`: Get available Kubernetes versions\n - `check-network`: Perform outbound network connectivity check\n - `nodepool-list`: List node pools in cluster\n - `nodepool-show`: Show node pool details\n - `account-list`: List Azure subscriptions\n\n- **Read-Write** (`readwrite`/`admin` access levels):\n - `create`: Create new cluster\n - `delete`: Delete cluster\n - `scale`: Scale cluster node count\n - `start`: Start a stopped cluster\n - `stop`: Stop a running cluster\n - `update`: Update cluster configuration\n - `upgrade`: Upgrade Kubernetes version\n - `nodepool-add`: Add node pool to cluster\n - `nodepool-delete`: Delete node pool\n - `nodepool-scale`: Scale node pool\n - `nodepool-upgrade`: Upgrade node pool\n - `account-set`: Set active subscription\n - `login`: Azure authentication\n\n- **Admin-Only** (`admin` access level):\n - `get-credentials`: Get cluster credentials for kubectl access\n\n \n\n\nNetwork Resource Management
\n\n**Tool:** `aks_network_resources`\n\nUnified tool for getting Azure network resource information used by AKS clusters.\n\n**Available Resource Types:**\n\n- `all`: Get information about all network resources\n- `vnet`: Virtual Network information\n- `subnet`: Subnet information\n- `nsg`: Network Security Group information\n- `route_table`: Route Table information\n- `load_balancer`: Load Balancer information\n- `private_endpoint`: Private endpoint information\n\n \n\n\nMonitoring and Diagnostics
\n\n**Tool:** `aks_monitoring`\n\nUnified tool for Azure monitoring and diagnostics operations for AKS clusters.\n\n**Available Operations:**\n\n- `metrics`: List metric values for resources\n- `resource_health`: Retrieve resource health events for AKS clusters\n- `app_insights`: Execute KQL queries against Application Insights telemetry data\n- `diagnostics`: Check if AKS cluster has diagnostic settings configured\n- `control_plane_logs`: Query AKS control plane logs with safety constraints\n and time range validation\n\n \n\n\nCompute Resources
\n\n**Tool:** `get_aks_vmss_info`\n\n- Get detailed VMSS configuration for node pools in the AKS cluster\n\n**Tool:** `collect_aks_node_logs`\n\nCollect system logs from AKS VMSS nodes for debugging and troubleshooting.\n\n**Parameters:**\n- `aks_resource_id`: AKS cluster resource ID\n- `vmss_name`: VMSS name (obtain from `get_aks_vmss_info` or `kubectl get nodes`)\n- `instance_id`: VMSS instance ID\n- `log_type`: Type of logs to collect (`kubelet`, `containerd`, `kernel`, `syslog`)\n- `lines`: Number of recent log lines to return (default: 500, max: 2000)\n- `since`: Time range for logs (e.g., `1h`, `30m`, `2d`) - takes precedence over `lines`\n- `level`: Log level filter (`ERROR`, `WARN`, `INFO`)\n- `filter`: Filter logs by keyword (case-insensitive text match)\n\n**Example Usage:**\n```json\n{\n \"aks_resource_id\": \"/subscriptions/.../managedClusters/myAKS\",\n \"vmss_name\": \"aks-nodepool1-12345678-vmss\",\n \"instance_id\": \"0\",\n \"log_type\": \"kubelet\",\n \"since\": \"1h\",\n \"level\": \"ERROR\",\n \"filter\": \"ImagePullBackOff\"\n}\n```\n\n**Limitations:**\n- Only supports Linux VMSS nodes (Windows nodes and standalone VMs are not supported yet)\n- Only one run command can execute at a time per VMSS instance\n\n**Tool:** `az_compute_operations`\n\nUnified tool for managing Azure Virtual Machines (VMs) and Virtual Machine Scale Sets (VMSS) used by AKS.\n\n**Available Operations:**\n\n- `show`: Get details of a VM/VMSS\n- `list`: List VMs/VMSS in subscription or resource group\n- `get-instance-view`: Get runtime status\n- `start`: Start VM\n- `stop`: Stop VM\n- `restart`: Restart VM/VMSS instances\n- `reimage`: Reimage VMSS instances (VM not supported for reimage)\n\n**Resource Types:** `vm` (single virtual machines), `vmss` (virtual machine scale sets)\n\n \n\n\nFleet Management
\n\n**Tool:** `az_fleet`\n\nComprehensive Azure Fleet management for multi-cluster scenarios.\n\n**Available Operations:**\n\n- **Fleet Operations**: list, show, create, update, delete, get-credentials\n- **Member Operations**: list, show, create, update, delete\n- **Update Run Operations**: list, show, create, start, stop, delete\n- **Update Strategy Operations**: list, show, create, delete\n- **ClusterResourcePlacement Operations**: list, show, get, create, delete\n\nSupports both Azure Fleet management and Kubernetes ClusterResourcePlacement\nCRD operations.\n\n \n\n\nDiagnostic Detectors
\n\n**Tool:** `aks_detector`\n\nUnified tool for executing AKS diagnostic detector operations.\n\n**Available Operations:**\n\n- `list`: List all available AKS cluster detectors\n- `run`: Run a specific AKS diagnostic detector\n- `run_by_category`: Run all detectors in a specific category\n\n**Parameters:**\n\n- `operation` (required): Operation to perform (`list`, `run`, or `run_by_category`)\n- `aks_resource_id` (required): AKS cluster resource ID\n- `detector_name` (required for `run` operation): Name of the detector to run\n- `category` (required for `run_by_category` operation): Detector category\n- `start_time` (required for `run` and `run_by_category` operations): Start time in UTC ISO format (within last 30 days)\n- `end_time` (required for `run` and `run_by_category` operations): End time in UTC ISO format (within last 30 days, max 24h from start)\n\n**Available Categories:**\n\n- Best Practices\n- Cluster and Control Plane Availability and Performance\n- Connectivity Issues\n- Create, Upgrade, Delete and Scale\n- Deprecations\n- Identity and Security\n- Node Health\n- Storage\n\n**Example Usage:**\n\n```json\n{\n \"operation\": \"list\",\n \"aks_resource_id\": \"/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx\"\n}\n```\n\n```json\n{\n \"operation\": \"run\",\n \"aks_resource_id\": \"/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx\",\n \"detector_name\": \"node-health-detector\",\n \"start_time\": \"2025-01-15T10:00:00Z\",\n \"end_time\": \"2025-01-15T12:00:00Z\"\n}\n```\n\n \n\n\nAzure Advisor
\n\n**Tool:** `aks_advisor_recommendation`\n\nRetrieve and manage Azure Advisor recommendations for AKS clusters.\n\n**Available Operations:**\n\n- `list`: List recommendations with filtering options\n- `report`: Generate recommendation reports\n- **Filter Options**: resource_group, cluster_names, category (Cost,\n HighAvailability, Performance, Security), severity (High, Medium, Low)\n\n \n\n\nKubernetes Operations
\n\n*Note: All Kubernetes tools (kubectl, helm, cilium, hubble) are enabled by default. Use `--enabled-components` to selectively enable specific components.*\n\n### Unified kubectl Tool (Default)\n\n**Tool:** `call_kubectl` *(default, available when `USE_LEGACY_TOOLS` is not set or set to `false`)*\n\nUnified tool for executing kubectl commands directly. This tool provides a flexible interface to run any `kubectl` command with full argument support.\n\n**Parameters:**\n- `args`: The kubectl command arguments (e.g., `get pods`, `describe node mynode`, `apply -f deployment.yaml`)\n\n**Example Usage:**\n```json\n{\n \"args\": \"get pods -n kube-system -o wide\"\n}\n```\n\n**Access Control:** Operations are restricted based on the configured access level:\n- **readonly**: Only read operations (get, describe, logs, etc.) are allowed\n- **readwrite/admin**: All operations including mutating commands (create, delete, apply, etc.)\n\n### Legacy kubectl Tools (Specialized)\n\n**Available when `USE_LEGACY_TOOLS=true`:**\n\n- **Read-Only** (all access levels):\n - `kubectl_resources`: View resources (get, describe) - filtered to read-only operations in readonly mode\n - `kubectl_diagnostics`: Debug and diagnose (logs, events, top, exec, cp)\n - `kubectl_cluster`: Cluster information (cluster-info, api-resources, api-versions, explain)\n - `kubectl_config`: Configuration management (diff, auth, config) - filtered to read-only operations in readonly mode\n\n- **Read-Write/Admin** (`readwrite`/`admin` access levels):\n - `kubectl_resources`: Full resource management (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)\n - `kubectl_workloads`: Workload lifecycle (run, expose, scale, autoscale, rollout)\n - `kubectl_metadata`: Metadata management (label, annotate, set)\n - `kubectl_config`: Full configuration management (diff, auth, certificate, config)\n\n### Helm\n\n**Tool:** `call_helm`\n\nHelm package manager for Kubernetes.\n\n### Cilium\n\n**Tool:** `call_cilium`\n\nCilium CLI for eBPF-based networking and security.\n\n### Hubble\n\n**Tool:** `call_hubble`\n\nHubble network observability for Cilium.\n\n \n\n\nReal-time Observability
\n\n**Tool:** `inspektor_gadget_observability`\n\nReal-time observability tool for Azure Kubernetes Service (AKS) clusters using\neBPF.\n\n**Available Actions:**\n\n- `deploy`: Deploy Inspektor Gadget to the cluster (via the AKS cluster extension)\n- `undeploy`: Remove the Inspektor Gadget cluster extension from the cluster\n- `is_deployed`: Check deployment status\n- `run`: Run one-shot gadgets\n- `start`: Start continuous gadgets\n- `stop`: Stop running gadgets\n- `get_results`: Retrieve gadget results\n- `list_gadgets`: List available gadgets\n\n**Available Gadgets:**\n\n- `observe_dns`: Monitor DNS requests and responses\n- `observe_tcp`: Monitor TCP connections\n- `observe_file_open`: Monitor file system operations\n- `observe_process_execution`: Monitor process execution\n- `observe_signal`: Monitor signal delivery\n- `observe_system_calls`: Monitor system calls\n- `top_file`: Top files by I/O operations\n- `top_tcp`: Top TCP connections by traffic\n- `tcpdump`: Capture network packets\n\n \n\n## How to install\n\n### Prerequisites\n\n1. Set up [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and authenticate:\n\n ```bash\n az login\n ```\n\n### VS Code with GitHub Copilot (Recommended)\n\n\n One-Click Installation with the AKS Extension
\n\nThe easiest way to get started with AKS-MCP is through the **Azure Kubernetes Service Extension for VS Code**.\n\n#### Step 1: Install the AKS Extension\n\n1. Open VS Code and go to Extensions (`Ctrl+Shift+X` on Windows/Linux or `Cmd+Shift+X` on macOS).\n1. Search for [Azure Kubernetes Service](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-aks-tools).\n1. Install the official Microsoft AKS extension.\n\n#### Step 2: Launch the AKS-MCP Server\n\n1. Open the **Command Palette** (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS).\n2. Search and run: **AKS: Setup AKS MCP Server**.\n\nUpon successful installation, the server will now be visible in **MCP: List Servers** (via Command Palette). From there, you can start the MCP server or view its status.\n\n#### Step 3: Start Using AKS-MCP\n\nOnce started, the MCP server will appear in the **Copilot Chat: Configure Tools** dropdown under `MCP Server: AKS MCP`, ready to enhance contextual prompts based on your AKS environment. By default, all AKS-MCP server tools are enabled. You can review the list of available tools and disable any that are not required for your specific scenario.\n\nTry a prompt like *\"List all my AKS clusters\"*, which will start using tools from the AKS-MCP server.\n\n#### WSL Configuration\n\nThe MCP configuration differs depending on whether VS Code is running on Windows or inside WSL:\n\n**🪟 Windows Host (VS Code on Windows)**: Use `\"command\": \"wsl\"` to invoke the WSL binary from Windows:\n\n```json\n{\n \"servers\": {\n \"aks-mcp\": {\n \"type\": \"stdio\",\n \"command\": \"wsl\",\n \"args\": [\n \"--\",\n \"/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp\"\n ]\n }\n }\n}\n```\n\n**🐧 Remote-WSL (VS Code running inside WSL)**: Call the binary directly or use a shell wrapper:\n\n```json\n{\n \"servers\": {\n \"aks-mcp\": {\n \"type\": \"stdio\",\n \"command\": \"bash\",\n \"args\": [\n \"-c\",\n \"/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp\"\n ]\n }\n }\n}\n```\n\n\n**🔧 Troubleshooting ENOENT Errors**\n\nIf you see \"spawn ENOENT\" errors, verify your VS Code environment:\n- **Windows host**: Check if the WSL binary path is correct and accessible via `wsl -- ls /path/to/aks-mcp`\n- **Remote-WSL**: Do NOT use `\"command\": \"wsl\"` - use direct paths or bash wrapper as shown above\n \n\n> **💡 Benefits**: The AKS extension handles binary downloads, updates, and configuration automatically, ensuring you always have the latest version with optimal settings.\n\n\n### Alternative Installation Methods\n\n\nManual Binary Installation
\n\n#### Step 1: Download the Binary\n\nChoose your platform and download the latest AKS-MCP binary:\n\n| Platform | Architecture | Download Link |\n|----------|-------------|---------------|\n| **Windows** | AMD64 | [📥 aks-mcp-windows-amd64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe) |\n| | ARM64 | [📥 aks-mcp-windows-arm64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-arm64.exe) |\n| **macOS** | Intel (AMD64) | [📥 aks-mcp-darwin-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-amd64) |\n| | Apple Silicon (ARM64) | [📥 aks-mcp-darwin-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-arm64) |\n| **Linux** | AMD64 | [📥 aks-mcp-linux-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64) |\n| | ARM64 | [📥 aks-mcp-linux-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-arm64) |\n\n#### Step 2: Configure VS Code\n\nAfter downloading, create a `.vscode/mcp.json` file in your workspace root with the path to your downloaded binary.\n\n##### Option A: Automated Setup Script\n\nFor quick setup, you can use these one-liner scripts that download the binary\nand create the configuration:\n\n*Windows (PowerShell):*\n\n```powershell\n# Download binary and create VS Code configuration\nmkdir -p .vscode ; Invoke-WebRequest -Uri \"https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe\" -OutFile \"aks-mcp.exe\" ; @{servers=@{\"aks-mcp-server\"=@{type=\"stdio\";command=\"$PWD\\aks-mcp.exe\";args=@()}}} | ConvertTo-Json -Depth 3 | Out-File \".vscode/mcp.json\" -Encoding UTF8\n```\n\n*macOS/Linux (Bash):*\n\n```bash\n# Download binary and create VS Code configuration\nmkdir -p .vscode && curl -sL https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64 -o aks-mcp && chmod +x aks-mcp && echo '{\"servers\":{\"aks-mcp-server\":{\"type\":\"stdio\",\"command\":\"'$PWD'/aks-mcp\",\"args\":[]}}}' > .vscode/mcp.json\n```\n\n##### Option B: Manual Configuration\n\n> **✨ Simple Setup**: Download the binary for your platform, then use the manual configuration below to set up the MCP server in VS Code.\n\n#### Manual VS Code Configuration\n\nYou can configure the AKS-MCP server in two ways:\n\n**1. Workspace-specific configuration** (recommended for project-specific usage):\n\nCreate a `.vscode/mcp.json` file in your workspace with the path to your downloaded binary:\n\n```json\n{\n \"servers\": {\n \"aks-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"\",\n \"args\": []\n }\n }\n}\n```\n\n**2. User-level configuration** (persistent across all workspaces):\n\nFor a persistent configuration that works across all your VS Code workspaces, add the MCP server to your VS Code user settings:\n\n1. Open VS Code Settings (Ctrl+, or Cmd+,)\n2. Search for \"mcp\" in the settings\n3. Add the following to your User Settings JSON:\n\n```json\n{\n \"github.copilot.chat.mcp.servers\": {\n \"aks-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"\",\n \"args\": []\n }\n }\n}\n```\n\n#### Step 3: Load the AKS-MCP server tools to Github Copilot\n\n1. If running on an older version of VS Code: restart VS Code i.e. close and\n reopen VS Code to load the new MCP server configuration.\n2. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)\n3. Click the **Tools** button or run /list in the Github Copilot window to see the list of available tools\n4. You should see the AKS-MCP tools in the list\n5. Try a prompt like: *\"List all my AKS clusters in subscription xxx\"*\n6. The agent will automatically use AKS-MCP tools to complete your request\n\n> **💡 Tip**: If you don't see the AKS-MCP tools after restarting, check the VS Code output panel for any MCP server connection errors and verify your binary path in `.vscode/mcp.json`.\n\n**Note**: Ensure you have authenticated with Azure CLI (`az login`) for the server to access your Azure resources.\n\n \n\n### Other MCP-Compatible Clients\n\n\nCustom Client Installation
\n\nFor other MCP-compatible AI clients like [Claude Desktop](https://claude.ai/) or [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli), configure the server in your MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"aks\": {\n \"command\": \"\",\n \"args\": []\n }\n }\n}\n```\n\n### 🤖 Custom MCP Client Installation\n\nYou can configure any MCP-compatible client to use the AKS-MCP server by running the binary directly:\n\n```bash\n# Run the server directly\n./aks-mcp\n```\n\n### 🔧 Manual Binary Installation\n\nFor direct binary usage without package managers:\n\n1. Download the latest release from the [releases page](https://github.com/Azure/aks-mcp/releases)\n2. Extract the binary to your preferred location\n3. Make it executable (on Unix systems):\n ```bash\n chmod +x aks-mcp\n ```\n4. Configure your MCP client to use the binary path\n\n \n\n### Options\n\nCommand line arguments:\n\n```sh\nUsage of ./aks-mcp:\n --access-level string Access level (readonly, readwrite, admin) (default \"readonly\")\n --enabled-components string Comma-separated list of enabled components (empty means all components enabled). Available: az_cli,monitor,fleet,network,compute,detectors,advisor,inspektorgadget,kubectl,helm,cilium,hubble\n --allow-namespaces string Comma-separated list of allowed Kubernetes namespaces (empty means all namespaces)\n --otlp-endpoint string OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317)\n --timeout int Timeout for command execution in seconds, default is 600s (default 600)\n --log-level string Log level (debug, info, warn, error) (default \"info\")\n```\n\n**Environment variables:**\n- `USE_LEGACY_TOOLS`: Set to `true` to use legacy specialized tools instead of unified tools (default: `false`)\n - `false` (default): Uses `call_az` for Azure operations and `call_kubectl` for Kubernetes operations\n - `true`: Uses legacy tools like `az_aks_operations`, `az_compute_operations`, and specialized kubectl tools\n- Standard Azure authentication environment variables are supported (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`)\n\n## Development\n\n### Prerequisites\n\n- **Go** ≥ `1.24.x` installed on your local machine\n- **Bash** available as `/usr/bin/env bash` (Makefile targets use multi-line recipes with fail-fast mode)\n- **GNU Make** `4.x` or later\n\n> **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.\n\n### Building from Source\n\nThis project includes a Makefile for convenient development, building, and testing. To see all available targets:\n\n```bash\nmake help\n```\n\n#### Quick Start\n\n```bash\n# Build the binary\nmake build\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-coverage\n\n# Format and lint code\nmake check\n\n# Build for all platforms\nmake release\n```\n\n#### Common Development Tasks\n\n```bash\n# Install dependencies\nmake deps\n\n# Build and run with --help\nmake run\n\n# Clean build artifacts\nmake clean\n\n# Install binary to GOBIN\nmake install\n```\n\n### Manual Build\n\nIf you prefer to build without the Makefile:\n\n```bash\ngo build -o aks-mcp ./cmd/aks-mcp\n```\n\n## Usage\n\nAsk any questions about your AKS clusters in your AI client, for example:\n\n```\nList all my AKS clusters in my subscription xxx.\n\nWhat is the network configuration of my AKS cluster?\n\nShow me the network security groups associated with my cluster.\n\nCreate a new Azure Fleet named prod-fleet in eastus region.\n\nList all members in my fleet.\n\nCreate a placement to deploy nginx workloads to clusters with app=frontend label.\n\nShow me all ClusterResourcePlacements in my fleet.\n```\n\n## Telemetry\n\nTelemetry collection is on by default.\n\nTo opt out, set the environment variable `AKS_MCP_COLLECT_TELEMETRY=false`.\n\n## Contributing\n\nWe welcome contributions to AKS-MCP! Whether you're fixing bugs, adding features, or improving documentation, your help makes this project better.\n\n**📖 [Read our detailed Contributing Guide](CONTRIBUTING.md)** for comprehensive information on:\n\n- Setting up your development environment\n- Running AKS-MCP locally and testing with AI agents\n- Understanding the codebase architecture\n- Adding new MCP tools and features\n- Testing guidelines and best practices\n- Submitting pull requests\n\n### Quick Start for Contributors\n\n1. **Prerequisites**: Go ≥ 1.24.x, Azure CLI, Git\n2. **Setup**: Fork the repo, clone locally, run `make deps && make build`\n3. **Test**: Run `make test` and `make check`\n4. **Develop**: Follow the component-based architecture in [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Contributor License Agreement\n\nMost 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.\n\nWhen 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.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft\ntrademarks or logos is subject to and must follow\n[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).\nUse of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.\nAny use of third-party trademarks or logos are subject to those third-party's policies.\n"}