Skip to content
Back to search

aks-mcp

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Azure/aks-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Azure/aks-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/azure--aks-mcp/badge.svg)](/listings/azure--aks-mcp)

HTML

<a href="/listings/azure--aks-mcp"><img src="/api/listings/azure--aks-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

1. Set up [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and authenticate:

   az login

VS Code with GitHub Copilot (Recommended)

<details> <summary> One-Click Installation with the AKS Extension </summary>

The easiest way to get started with AKS-MCP is through the **Azure Kubernetes Service Extension for VS Code**.

Step 1: Install the AKS Extension

1. Open VS Code and go to Extensions (`Ctrl+Shift+X` on Windows/Linux or `Cmd+Shift+X` on macOS). 1. Search for [Azure Kubernetes Service](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-aks-tools). 1. Install the official Microsoft AKS extension.

Step 2: Launch the AKS-MCP Server

1. Open the **Command Palette** (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS). 2. Search and run: **AKS: Setup AKS MCP Server**.

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

Step 3: Start Using AKS-MCP

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

Try a prompt like *"List all my AKS clusters"*, which will start using tools from the AKS-MCP server.

WSL Configuration

The MCP configuration differs depending on whether VS Code is running on Windows or inside WSL:

**πŸͺŸ Windows Host (VS Code on Windows)**: Use `"command": "wsl"` to invoke the WSL binary from Windows:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "--",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
      ]
    }
  }
}

**🐧 Remote-WSL (VS Code running inside WSL)**: Call the binary directly or use a shell wrapper:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
      ]
    }
  }
}

**πŸ”§ Troubleshooting ENOENT Errors**

If you see "spawn ENOENT" errors, verify your VS Code environment: - **Windows host**: Check if the WSL binary path is correct and accessible via `wsl -- ls /path/to/aks-mcp` - **Remote-WSL**: Do NOT use `"command": "wsl"` - use direct paths or bash wrapper as shown above </details>

> **πŸ’‘ Benefits**: The AKS extension handles binary downloads, updates, and configuration automatically, ensuring you always have the latest version with optimal settings.

Alternative Installation Methods

<details> <summary>Manual Binary Installation</summary>

Step 1: Download the Binary

Choose your platform and download the latest AKS-MCP binary:

| Platform | Architecture | Download Link | |----------|-------------|---------------| | **Windows** | AMD64 | [πŸ“₯ aks-mcp-windows-amd64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe) | | | ARM64 | [πŸ“₯ aks-mcp-windows-arm64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-arm64.exe) | | **macOS** | Intel (AMD64) | [πŸ“₯ aks-mcp-darwin-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-amd64) | | | Apple Silicon (ARM64) | [πŸ“₯ aks-mcp-darwin-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-arm64) | | **Linux** | AMD64 | [πŸ“₯ aks-mcp-linux-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64) | | | ARM64 | [πŸ“₯ aks-mcp-linux-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-arm64) |

Step 2: Configure VS Code

After downloading, create a `.vscode/mcp.json` file in your workspace root with the path to your downloaded binary.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 859 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AKS-MCP
  2. [![SafeSkill 92/100](https://img.shields.io/badge/SafeSkill-92%2F100_Verified%20Safe-brightgreen)](https://safeskill.dev/scan/azure-aks-mcp)
  3. The AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants
  4. to interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge
  5. between AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI
  6. assistants) and AKS, translating natural language requests into AKS operations
  7. and returning the results in a format the AI tools can understand.
  8. It allows AI tools to:
  9. - Operate (CRUD) AKS resources
  10. - Retrieve details related to AKS clusters (VNets, Subnets, NSGs, Route Tables, etc.)
  11. - Manage Azure Fleet operations for multi-cluster scenarios
  12. ## Supported Deployment Model and Security Considerations
  13. **AKS-MCP is designed to be run locally, by a single trusted user, as a bridge
  14. between that user's own AI assistant and their own Azure/AKS resources.** This
  15. is the only deployment model the project supports and hardens for.
  16. ### The trust boundary
  17. AKS-MCP executes command-line tools β€” including `az`, `kubectl`, `helm`,
  18. `cilium`, and `hubble` β€” **using the identity of the process it runs as**. It
  19. does not perform per-caller authorization, and it does not attempt to sandbox
  20. the commands it runs. Therefore:
  21. > **Anyone who can invoke AKS-MCP tools effectively has the full Azure and
  22. > Kubernetes privileges of the identity AKS-MCP is running under.**
  23. This includes the ability to obtain reusable credentials. For example, in
  24. `readwrite` or `admin` mode a caller can reach Azure Resource Manager and AKS
  25. with the server identity's full authority, and `kubectl` or `helm` can be used
  26. to read Secrets, mint service account tokens, or deploy arbitrary workloads
  27. into the cluster. This is an inherent consequence of exposing a CLI execution
  28. surface β€” it is not prevented by `--access-level`.
  29. Specific credential-returning Azure CLI commands (such as
  30. `az account get-access-token` and `az aks get-credentials`) are rejected by an
  31. explicit denylist. That denylist reduces accidental exposure β€” it is **not** a
  32. security boundary, it does not cover the `kubectl`, `helm`, `cilium`, or
  33. `hubble` surfaces, and it must not be relied upon to contain an untrusted
  34. caller.
  35. **Treat the ability to call AKS-MCP as equivalent to handing over a shell that
  36. is already logged in as the server identity.**
  37. ### Network exposure and local authority
  38. Removing HTTP/SSE transports and the official remote deployment artifacts
  39. removes the supported network-reachable service and its remote-caller threat
  40. model. In the supported configuration, AKS-MCP has no listener that accepts
  41. requests from the network.
  42. This does **not** make the local MCP client, its prompts, or `--access-level`
  43. an authorization boundary. A person or process that controls the local client,
  44. its server configuration, or AKS-MCP can normally run the same CLI commands
  45. under the same identity without AKS-MCP. Protecting the workstation, client
  46. configuration, and local credentials remains the operator's responsibility.
  47. The `call_az` tool does not support `az rest`, including GET requests to Azure
  48. URLs. This restriction is enforced by the `azure-api-mcp` dependency in every
  49. access mode and cannot be overridden by security policies or read-only patterns.
  50. Use resource-specific commands such as `az aks show` or `az resource show` instead.
  51. ### What `--access-level` is and is not
  52. `--access-level` (`readonly` / `readwrite` / `admin`) is a **guardrail to reduce
  53. accidental damage** from an AI assistant that misinterprets a request. It is
  54. **not** a security boundary against a deliberately malicious caller, and it must
  55. not be relied upon to contain an untrusted party. Do not expose AKS-MCP to
  56. callers you would not grant the underlying Azure/Kubernetes credentials to
  57. directly.
  58. ### Recommended (supported) setup
  59. - Run as a local subprocess, launched on demand by your local MCP client.
  60. - Authenticate with your own developer identity via `az login`.
  61. - Grant the identity only the Azure/Kubernetes permissions you actually need.
  62. ### Unsupported deployment models
  63. AKS-MCP supports only stdio and must be launched as a local subprocess by an
  64. MCP client. Do not expose it through HTTP, SSE, a container service, Helm,
  65. Kubernetes, a proxy, or a gateway. Any third-party bridge is outside the
  66. project's security and support boundary.
  67. ## How it works
  68. AKS-MCP connects to Azure using the Azure SDK and provides a set of tools that
  69. AI assistants can use to interact with AKS resources. It leverages the Model
  70. Context Protocol (MCP) to facilitate this communication, enabling AI tools to
  71. make API calls to Azure and interpret the responses.
  72. ## Azure CLI Authentication
  73. AKS-MCP uses Azure CLI (az) for AKS operations. Azure CLI authentication is attempted in this order:
  74. 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`
  75. 1. 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`
  76. 1. 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`
  77. 1. 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`
  78. 1. 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.
  79. Optional subscription selection:
  80. - If `AZURE_SUBSCRIPTION_ID` is set, AKS-MCP will run `az account set --subscription SUBSCRIPTION_ID` after login.
  81. Notes and security:
  82. - The federated token file must be exactly `/var/run/secrets/azure/tokens/azure-identity-token` and is strictly validated; other paths are rejected.
  83. - After each login, AKS-MCP verifies authentication with `az account show --query id -o tsv`.
  84. - Ensure the Azure CLI is installed and on PATH.
  85. Environment variables used:
  86. - `AZURE_TENANT_ID`
  87. - `AZURE_CLIENT_ID`
  88. - `AZURE_CLIENT_SECRET`
  89. - `AZURE_FEDERATED_TOKEN_FILE`
  90. - `AZURE_SUBSCRIPTION_ID`
  91. - `AZURE_MANAGED_IDENTITY` (set to `system` to opt into system-assigned managed identity)
  92. ## Available Tools
  93. The AKS-MCP server provides consolidated tools for interacting with AKS
  94. 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`.
  95. 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:
  96. 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).
  97. 2. In the "args" section of AKS-MCP, add the following parameters: "--access-level", "readwrite" / "admin"
  98. For example:
  99. ```
  100. "args": [
  101. "--access-level",
  102. "readwrite"
  103. ]
  104. ```
  105. These tools have been designed to provide comprehensive functionality
  106. through unified interfaces:
  107. <details>
  108. <summary>Azure CLI Operations (Unified Tool)</summary>
  109. **Tool:** `call_az` *(default, available when `USE_LEGACY_TOOLS` is not set or set to `false`)*
  110. Unified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.
  111. **Parameters:**
  112. - `cli_command`: The complete Azure CLI command to execute (e.g., `az aks list --resource-group myRG`, `az vm list --subscription <sub-id>`)
  113. - `timeout`: Optional timeout in seconds (default: 120)
  114. **Example Usage:**
  115. ```json
  116. {
  117. "cli_command": "az aks list --resource-group myResourceGroup --output json"
  118. }
  119. ```
  120. **Access Control:**
  121. - **readonly**: Only read operations are allowed
  122. - **readwrite/admin**: Both read and write operations are allowed
  123. **Important:** Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).
  124. </details>
  125. <details>
  126. <summary>AKS Cluster Management (Legacy Tool)</summary>
  127. **Tool:** `az_aks_operations` *(available when `USE_LEGACY_TOOLS=true`)*
  128. Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.
  129. **Available Operations:**
  130. - **Read-Only** (all access levels):
  131. - `show`: Show cluster details
  132. - `list`: List clusters in subscription/resource group
  133. - `get-versions`: Get available Kubernetes versions
  134. - `check-network`: Perform outbound network connectivity check
  135. - `nodepool-list`: List node pools in cluster
  136. - `nodepool-show`: Show node pool details
  137. - `account-list`: List Azure subscriptions
  138. - **Read-Write** (`readwrite`/`admin` access levels):
  139. - `create`: Create new cluster
  140. - `delete`: Delete cluster
  141. - `scale`: Scale cluster node count
  142. - `start`: Start a stopped cluster
  143. - `stop`: Stop a running cluster
  144. - `update`: Update cluster configuration
  145. - `upgrade`: Upgrade Kubernetes version
  146. - `nodepool-add`: Add node pool to cluster
  147. - `nodepool-delete`: Delete node pool
  148. - `nodepool-scale`: Scale node pool
  149. - `nodepool-upgrade`: Upgrade node pool
  150. - `account-set`: Set active subscription
  151. - `login`: Azure authentication
  152. - **Admin-Only** (`admin` access level):
  153. - `get-credentials`: Get cluster credentials for kubectl access
  154. </details>
  155. <details>
  156. <summary>Network Resource Management</summary>
  157. **Tool:** `aks_network_resources`
  158. Unified tool for getting Azure network resource information used by AKS clusters.
  159. **Available Resource Types:**
  160. - `all`: Get information about all network resources
  161. - `vnet`: Virtual Network information
  162. - `subnet`: Subnet information
  163. - `nsg`: Network Security Group information
  164. - `route_table`: Route Table information
  165. - `load_balancer`: Load Balancer information
  166. - `private_endpoint`: Private endpoint information
  167. </details>
  168. <details>
  169. <summary>Monitoring and Diagnostics</summary>
  170. **Tool:** `aks_monitoring`
  171. Unified tool for Azure monitoring and diagnostics operations for AKS clusters.
  172. **Available Operations:**
  173. - `metrics`: List metric values for resources
  174. - `resource_health`: Retrieve resource health events for AKS clusters
  175. - `app_insights`: Execute KQL queries against Application Insights telemetry data
  176. - `diagnostics`: Check if AKS cluster has diagnostic settings configured
  177. - `control_plane_logs`: Query AKS control plane logs with safety constraints
  178. and time range validation
  179. </details>
  180. <details>
  181. <summary>Compute Resources</summary>
  182. **Tool:** `get_aks_vmss_info`
  183. - Get detailed VMSS configuration for node pools in the AKS cluster
  184. **Tool:** `collect_aks_node_logs`
  185. Collect system logs from AKS VMSS nodes for debugging and troubleshooting.
  186. **Parameters:**
  187. - `aks_resource_id`: AKS cluster resource ID
  188. - `vmss_name`: VMSS name (obtain from `get_aks_vmss_info` or `kubectl get nodes`)
  189. - `instance_id`: VMSS instance ID
  190. - `log_type`: Type of logs to collect (`kubelet`, `containerd`, `kernel`, `syslog`)
  191. - `lines`: Number of recent log lines to return (default: 500, max: 2000)
  192. - `since`: Time range for logs (e.g., `1h`, `30m`, `2d`) - takes precedence over `lines`
  193. - `level`: Log level filter (`ERROR`, `WARN`, `INFO`)
  194. - `filter`: Filter logs by keyword (case-insensitive text match)
  195. **Example Usage:**
  196. ```json
  197. {
  198. "aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
  199. "vmss_name": "aks-nodepool1-12345678-vmss",
  200. "instance_id": "0",
  201. "log_type": "kubelet",
  202. "since": "1h",
  203. "level": "ERROR",
  204. "filter": "ImagePullBackOff"
  205. }
  206. ```
  207. **Limitations:**
  208. - Only supports Linux VMSS nodes (Windows nodes and standalone VMs are not supported yet)
  209. - Only one run command can execute at a time per VMSS instance
  210. **Tool:** `az_compute_operations`
  211. Unified tool for managing Azure Virtual Machines (VMs) and Virtual Machine Scale Sets (VMSS) used by AKS.
  212. **Available Operations:**
  213. - `show`: Get details of a VM/VMSS
  214. - `list`: List VMs/VMSS in subscription or resource group
  215. - `get-instance-view`: Get runtime status
  216. - `start`: Start VM
  217. - `stop`: Stop VM
  218. - `restart`: Restart VM/VMSS instances
  219. - `reimage`: Reimage VMSS instances (VM not supported for reimage)
  220. **Resource Types:** `vm` (single virtual machines), `vmss` (virtual machine scale sets)
  221. </details>
  222. <details>
  223. <summary>Fleet Management</summary>
  224. **Tool:** `az_fleet`
  225. Comprehensive Azure Fleet management for multi-cluster scenarios.
  226. **Available Operations:**
  227. - **Fleet Operations**: list, show, create, update, delete, get-credentials
  228. - **Member Operations**: list, show, create, update, delete
  229. - **Update Run Operations**: list, show, create, start, stop, delete
  230. - **Update Strategy Operations**: list, show, create, delete
  231. - **ClusterResourcePlacement Operations**: list, show, get, create, delete
  232. Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement
  233. CRD operations.
  234. </details>
  235. <details>
  236. <summary>Diagnostic Detectors</summary>
  237. **Tool:** `aks_detector`
  238. Unified tool for executing AKS diagnostic detector operations.
  239. **Available Operations:**
  240. - `list`: List all available AKS cluster detectors
  241. - `run`: Run a specific AKS diagnostic detector
  242. - `run_by_category`: Run all detectors in a specific category
  243. **Parameters:**
  244. - `operation` (required): Operation to perform (`list`, `run`, or `run_by_category`)
  245. - `aks_resource_id` (required): AKS cluster resource ID
  246. - `detector_name` (required for `run` operation): Name of the detector to run
  247. - `category` (required for `run_by_category` operation): Detector category
  248. - `start_time` (required for `run` and `run_by_category` operations): Start time in UTC ISO format (within last 30 days)
  249. - `end_time` (required for `run` and `run_by_category` operations): End time in UTC ISO format (within last 30 days, max 24h from start)
  250. **Available Categories:**
  251. - Best Practices
  252. - Cluster and Control Plane Availability and Performance
  253. - Connectivity Issues
  254. - Create, Upgrade, Delete and Scale
  255. - Deprecations
  256. - Identity and Security
  257. - Node Health
  258. - Storage
  259. **Example Usage:**
  260. ```json
  261. {
  262. "operation": "list",
  263. "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
  264. }
  265. ```
  266. ```json
  267. {
  268. "operation": "run",
  269. "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
  270. "detector_name": "node-health-detector",
  271. "start_time": "2025-01-15T10:00:00Z",
  272. "end_time": "2025-01-15T12:00:00Z"
  273. }
  274. ```
  275. </details>
  276. <details>
  277. <summary>Azure Advisor</summary>
  278. **Tool:** `aks_advisor_recommendation`
  279. Retrieve and manage Azure Advisor recommendations for AKS clusters.
  280. **Available Operations:**
  281. - `list`: List recommendations with filtering options
  282. - `report`: Generate recommendation reports
  283. - **Filter Options**: resource_group, cluster_names, category (Cost,
  284. HighAvailability, Performance, Security), severity (High, Medium, Low)
  285. </details>
  286. <details>
  287. <summary>Kubernetes Operations</summary>
  288. *Note: All Kubernetes tools (kubectl, helm, cilium, hubble) are enabled by default. Use `--enabled-components` to selectively enable specific components.*
  289. ### Unified kubectl Tool (Default)
  290. **Tool:** `call_kubectl` *(default, available when `USE_LEGACY_TOOLS` is not set or set to `false`)*
  291. Unified tool for executing kubectl commands directly. This tool provides a flexible interface to run any `kubectl` command with full argument support.
  292. **Parameters:**
  293. - `args`: The kubectl command arguments (e.g., `get pods`, `describe node mynode`, `apply -f deployment.yaml`)
  294. **Example Usage:**
  295. ```json
  296. {
  297. "args": "get pods -n kube-system -o wide"
  298. }
  299. ```
  300. **Access Control:** Operations are restricted based on the configured access level:
  301. - **readonly**: Only read operations (get, describe, logs, etc.) are allowed
  302. - **readwrite/admin**: All operations including mutating commands (create, delete, apply, etc.)
  303. ### Legacy kubectl Tools (Specialized)
  304. **Available when `USE_LEGACY_TOOLS=true`:**
  305. - **Read-Only** (all access levels):
  306. - `kubectl_resources`: View resources (get, describe) - filtered to read-only operations in readonly mode
  307. - `kubectl_diagnostics`: Debug and diagnose (logs, events, top, exec, cp)
  308. - `kubectl_cluster`: Cluster information (cluster-info, api-resources, api-versions, explain)
  309. - `kubectl_config`: Configuration management (diff, auth, config) - filtered to read-only operations in readonly mode
  310. - **Read-Write/Admin** (`readwrite`/`admin` access levels):
  311. - `kubectl_resources`: Full resource management (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
  312. - `kubectl_workloads`: Workload lifecycle (run, expose, scale, autoscale, rollout)
  313. - `kubectl_metadata`: Metadata management (label, annotate, set)
  314. - `kubectl_config`: Full configuration management (diff, auth, certificate, config)
  315. ### Helm
  316. **Tool:** `call_helm`
  317. Helm package manager for Kubernetes.
  318. ### Cilium
  319. **Tool:** `call_cilium`
  320. Cilium CLI for eBPF-based networking and security.
  321. ### Hubble
  322. **Tool:** `call_hubble`
  323. Hubble network observability for Cilium.
  324. </details>
  325. <details>
  326. <summary>Real-time Observability</summary>
  327. **Tool:** `inspektor_gadget_observability`
  328. Real-time observability tool for Azure Kubernetes Service (AKS) clusters using
  329. eBPF.
  330. **Available Actions:**
  331. - `deploy`: Deploy Inspektor Gadget to the cluster (via the AKS cluster extension)
  332. - `undeploy`: Remove the Inspektor Gadget cluster extension from the cluster
  333. - `is_deployed`: Check deployment status
  334. - `run`: Run one-shot gadgets
  335. - `start`: Start continuous gadgets
  336. - `stop`: Stop running gadgets
  337. - `get_results`: Retrieve gadget results
  338. - `list_gadgets`: List available gadgets
  339. **Available Gadgets:**
  340. - `observe_dns`: Monitor DNS requests and responses
  341. - `observe_tcp`: Monitor TCP connections
  342. - `observe_file_open`: Monitor file system operations
  343. - `observe_process_execution`: Monitor process execution
  344. - `observe_signal`: Monitor signal delivery
  345. - `observe_system_calls`: Monitor system calls
  346. - `top_file`: Top files by I/O operations
  347. - `top_tcp`: Top TCP connections by traffic
  348. - `tcpdump`: Capture network packets
  349. </details>
  350. ## How to install
  351. ### Prerequisites
  352. 1. Set up [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and authenticate:
  353. ```bash
  354. az login
  355. ```
  356. ### VS Code with GitHub Copilot (Recommended)
  357. <details>
  358. <summary> One-Click Installation with the AKS Extension </summary>
  359. The easiest way to get started with AKS-MCP is through the **Azure Kubernetes Service Extension for VS Code**.
  360. #### Step 1: Install the AKS Extension
  361. 1. Open VS Code and go to Extensions (`Ctrl+Shift+X` on Windows/Linux or `Cmd+Shift+X` on macOS).
  362. 1. Search for [Azure Kubernetes Service](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-aks-tools).
  363. 1. Install the official Microsoft AKS extension.
  364. #### Step 2: Launch the AKS-MCP Server
  365. 1. Open the **Command Palette** (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS).
  366. 2. Search and run: **AKS: Setup AKS MCP Server**.
  367. Upon 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.
  368. #### Step 3: Start Using AKS-MCP
  369. Once 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.
  370. Try a prompt like *"List all my AKS clusters"*, which will start using tools from the AKS-MCP server.
  371. #### WSL Configuration
  372. The MCP configuration differs depending on whether VS Code is running on Windows or inside WSL:
  373. **πŸͺŸ Windows Host (VS Code on Windows)**: Use `"command": "wsl"` to invoke the WSL binary from Windows:
  374. ```json
  375. {
  376. "servers": {
  377. "aks-mcp": {
  378. "type": "stdio",
  379. "command": "wsl",
  380. "args": [
  381. "--",
  382. "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
  383. ]
  384. }
  385. }
  386. }
  387. ```
  388. **🐧 Remote-WSL (VS Code running inside WSL)**: Call the binary directly or use a shell wrapper:
  389. ```json
  390. {
  391. "servers": {
  392. "aks-mcp": {
  393. "type": "stdio",
  394. "command": "bash",
  395. "args": [
  396. "-c",
  397. "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
  398. ]
  399. }
  400. }
  401. }
  402. ```
  403. **πŸ”§ Troubleshooting ENOENT Errors**
  404. If you see "spawn ENOENT" errors, verify your VS Code environment:
  405. - **Windows host**: Check if the WSL binary path is correct and accessible via `wsl -- ls /path/to/aks-mcp`
  406. - **Remote-WSL**: Do NOT use `"command": "wsl"` - use direct paths or bash wrapper as shown above
  407. </details>
  408. > **πŸ’‘ Benefits**: The AKS extension handles binary downloads, updates, and configuration automatically, ensuring you always have the latest version with optimal settings.
  409. ### Alternative Installation Methods
  410. <details>
  411. <summary>Manual Binary Installation</summary>
  412. #### Step 1: Download the Binary
  413. Choose your platform and download the latest AKS-MCP binary:
  414. | Platform | Architecture | Download Link |
  415. |----------|-------------|---------------|
  416. | **Windows** | AMD64 | [πŸ“₯ aks-mcp-windows-amd64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe) |
  417. | | ARM64 | [πŸ“₯ aks-mcp-windows-arm64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-arm64.exe) |
  418. | **macOS** | Intel (AMD64) | [πŸ“₯ aks-mcp-darwin-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-amd64) |
  419. | | Apple Silicon (ARM64) | [πŸ“₯ aks-mcp-darwin-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-arm64) |
  420. | **Linux** | AMD64 | [πŸ“₯ aks-mcp-linux-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64) |
  421. | | ARM64 | [πŸ“₯ aks-mcp-linux-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-arm64) |
  422. #### Step 2: Configure VS Code
  423. After downloading, create a `.vscode/mcp.json` file in your workspace root with the path to your downloaded binary.
  424. ##### Option A: Automated Setup Script
  425. For quick setup, you can use these one-liner scripts that download the binary
  426. and create the configuration:
  427. *Windows (PowerShell):*
  428. ```powershell
  429. # Download binary and create VS Code configuration
  430. mkdir -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
  431. ```
  432. *macOS/Linux (Bash):*
  433. ```bash
  434. # Download binary and create VS Code configuration
  435. mkdir -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
  436. ```
  437. ##### Option B: Manual Configuration
  438. > **✨ Simple Setup**: Download the binary for your platform, then use the manual configuration below to set up the MCP server in VS Code.
  439. #### Manual VS Code Configuration
  440. You can configure the AKS-MCP server in two ways:
  441. **1. Workspace-specific configuration** (recommended for project-specific usage):
  442. Create a `.vscode/mcp.json` file in your workspace with the path to your downloaded binary:
  443. ```json
  444. {
  445. "servers": {
  446. "aks-mcp-server": {
  447. "type": "stdio",
  448. "command": "<enter the file path>",
  449. "args": []
  450. }
  451. }
  452. }
  453. ```
  454. **2. User-level configuration** (persistent across all workspaces):
  455. For a persistent configuration that works across all your VS Code workspaces, add the MCP server to your VS Code user settings:
  456. 1. Open VS Code Settings (Ctrl+, or Cmd+,)
  457. 2. Search for "mcp" in the settings
  458. 3. Add the following to your User Settings JSON:
  459. ```json
  460. {
  461. "github.copilot.chat.mcp.servers": {
  462. "aks-mcp-server": {
  463. "type": "stdio",
  464. "command": "<enter the file path>",
  465. "args": []
  466. }
  467. }
  468. }
  469. ```
  470. #### Step 3: Load the AKS-MCP server tools to Github Copilot
  471. 1. If running on an older version of VS Code: restart VS Code i.e. close and
  472. reopen VS Code to load the new MCP server configuration.
  473. 2. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)
  474. 3. Click the **Tools** button or run /list in the Github Copilot window to see the list of available tools
  475. 4. You should see the AKS-MCP tools in the list
  476. 5. Try a prompt like: *"List all my AKS clusters in subscription xxx"*
  477. 6. The agent will automatically use AKS-MCP tools to complete your request
  478. > **πŸ’‘ 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`.
  479. **Note**: Ensure you have authenticated with Azure CLI (`az login`) for the server to access your Azure resources.
  480. </details>
  481. ### Other MCP-Compatible Clients
  482. <details>
  483. <summary>Custom Client Installation</summary>
  484. For 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:
  485. ```json
  486. {
  487. "mcpServers": {
  488. "aks": {
  489. "command": "<path of binary aks-mcp>",
  490. "args": []
  491. }
  492. }
  493. }
  494. ```
  495. ### πŸ€– Custom MCP Client Installation
  496. You can configure any MCP-compatible client to use the AKS-MCP server by running the binary directly:
  497. ```bash
  498. # Run the server directly
  499. ./aks-mcp
  500. ```
  501. ### πŸ”§ Manual Binary Installation
  502. For direct binary usage without package managers:
  503. 1. Download the latest release from the [releases page](https://github.com/Azure/aks-mcp/releases)
  504. 2. Extract the binary to your preferred location
  505. 3. Make it executable (on Unix systems):
  506. ```bash
  507. chmod +x aks-mcp
  508. ```
  509. 4. Configure your MCP client to use the binary path
  510. </details>
  511. ### Options
  512. Command line arguments:
  513. ```sh
  514. Usage of ./aks-mcp:
  515. --access-level string Access level (readonly, readwrite, admin) (default "readonly")
  516. --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
  517. --allow-namespaces string Comma-separated list of allowed Kubernetes namespaces (empty means all namespaces)
  518. --otlp-endpoint string OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317)
  519. --timeout int Timeout for command execution in seconds, default is 600s (default 600)
  520. --log-level string Log level (debug, info, warn, error) (default "info")
  521. ```
  522. **Environment variables:**
  523. - `USE_LEGACY_TOOLS`: Set to `true` to use legacy specialized tools instead of unified tools (default: `false`)
  524. - `false` (default): Uses `call_az` for Azure operations and `call_kubectl` for Kubernetes operations
  525. - `true`: Uses legacy tools like `az_aks_operations`, `az_compute_operations`, and specialized kubectl tools
  526. - Standard Azure authentication environment variables are supported (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`)
  527. ## Development
  528. ### Prerequisites
  529. - **Go** β‰₯ `1.24.x` installed on your local machine
  530. - **Bash** available as `/usr/bin/env bash` (Makefile targets use multi-line recipes with fail-fast mode)
  531. - **GNU Make** `4.x` or later
  532. > **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.
  533. ### Building from Source
  534. This project includes a Makefile for convenient development, building, and testing. To see all available targets:
  535. ```bash
  536. make help
  537. ```
  538. #### Quick Start
  539. ```bash
  540. # Build the binary
  541. make build
  542. # Run tests
  543. make test
  544. # Run tests with coverage
  545. make test-coverage
  546. # Format and lint code
  547. make check
  548. # Build for all platforms
  549. make release
  550. ```
  551. #### Common Development Tasks
  552. ```bash
  553. # Install dependencies
  554. make deps
  555. # Build and run with --help
  556. make run
  557. # Clean build artifacts
  558. make clean
  559. # Install binary to GOBIN
  560. make install
  561. ```
  562. ### Manual Build
  563. If you prefer to build without the Makefile:
  564. ```bash
  565. go build -o aks-mcp ./cmd/aks-mcp
  566. ```
  567. ## Usage
  568. Ask any questions about your AKS clusters in your AI client, for example:
  569. ```
  570. List all my AKS clusters in my subscription xxx.
  571. What is the network configuration of my AKS cluster?
  572. Show me the network security groups associated with my cluster.
  573. Create a new Azure Fleet named prod-fleet in eastus region.
  574. List all members in my fleet.
  575. Create a placement to deploy nginx workloads to clusters with app=frontend label.
  576. Show me all ClusterResourcePlacements in my fleet.
  577. ```
  578. ## Telemetry
  579. Telemetry collection is on by default.
  580. To opt out, set the environment variable `AKS_MCP_COLLECT_TELEMETRY=false`.
  581. ## Contributing
  582. We welcome contributions to AKS-MCP! Whether you're fixing bugs, adding features, or improving documentation, your help makes this project better.
  583. **πŸ“– [Read our detailed Contributing Guide](CONTRIBUTING.md)** for comprehensive information on:
  584. - Setting up your development environment
  585. - Running AKS-MCP locally and testing with AI agents
  586. - Understanding the codebase architecture
  587. - Adding new MCP tools and features
  588. - Testing guidelines and best practices
  589. - Submitting pull requests
  590. ### Quick Start for Contributors
  591. 1. **Prerequisites**: Go β‰₯ 1.24.x, Azure CLI, Git
  592. 2. **Setup**: Fork the repo, clone locally, run `make deps && make build`
  593. 3. **Test**: Run `make test` and `make check`
  594. 4. **Develop**: Follow the component-based architecture in [CONTRIBUTING.md](CONTRIBUTING.md)
  595. ### Contributor License Agreement
  596. 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.
  597. 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.
  598. This 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.
  599. ## Trademarks
  600. This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
  601. trademarks or logos is subject to and must follow
  602. [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
  603. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
  604. Any use of third-party trademarks or logos are subject to those third-party's policies.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.