AKS-MCP

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

Supported Deployment Model and Security Considerations

AKS-MCP is designed to be run locally, by a single trusted user, as a bridge between that user's own AI assistant and their own Azure/AKS resources. This is the only deployment model the project supports and hardens for.

The trust boundary

AKS-MCP executes command-line tools — including az, kubectl, helm, cilium, and hubble — using the identity of the process it runs as. It does not perform per-caller authorization, and it does not attempt to sandbox the commands it runs. Therefore:

Anyone who can invoke AKS-MCP tools effectively has the full Azure and Kubernetes privileges of the identity AKS-MCP is running under.

This includes the ability to obtain reusable credentials. For example, in readwrite or admin mode a caller can reach Azure Resource Manager and AKS with the server identity's full authority, and kubectl or helm can be used to read Secrets, mint service account tokens, or deploy arbitrary workloads into the cluster. This is an inherent consequence of exposing a CLI execution surface — it is not prevented by --access-level.

Specific credential-returning Azure CLI commands (such as az account get-access-token and az aks get-credentials) are rejected by an explicit denylist. That denylist reduces accidental exposure — it is not a security boundary, it does not cover the kubectl, helm, cilium, or hubble surfaces, and it must not be relied upon to contain an untrusted caller.

Treat the ability to call AKS-MCP as equivalent to handing over a shell that is already logged in as the server identity.

Network exposure and local authority

Removing HTTP/SSE transports and the official remote deployment artifacts removes the supported network-reachable service and its remote-caller threat model. In the supported configuration, AKS-MCP has no listener that accepts requests from the network.

This does not make the local MCP client, its prompts, or --access-level an authorization boundary. A person or process that controls the local client, its server configuration, or AKS-MCP can normally run the same CLI commands under the same identity without AKS-MCP. Protecting the workstation, client configuration, and local credentials remains the operator's responsibility.

What --access-level is and is not

--access-level (readonly / readwrite / admin) is a guardrail to reduce accidental damage from an AI assistant that misinterprets a request. It is not a security boundary against a deliberately malicious caller, and it must not be relied upon to contain an untrusted party. Do not expose AKS-MCP to callers you would not grant the underlying Azure/Kubernetes credentials to directly.

Recommended (supported) setup

• Run as a local subprocess, launched on demand by your local MCP client.
• Authenticate with your own developer identity via az login.
• Grant the identity only the Azure/Kubernetes permissions you actually need.

Unsupported deployment models

AKS-MCP supports only stdio and must be launched as a local subprocess by an MCP client. Do not expose it through HTTP, SSE, a container service, Helm, Kubernetes, a proxy, or a gateway. Any third-party bridge is outside the project's security and support boundary.

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:

"args": [
  "--access-level",
  "readwrite"
]

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

{
  "cli_command": "az aks list --resource-group myResourceGroup --output json"
}

{
  "aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
  "vmss_name": "aks-nodepool1-12345678-vmss",
  "instance_id": "0",
  "log_type": "kubelet",
  "since": "1h",
  "level": "ERROR",
  "filter": "ImagePullBackOff"
}

{
  "operation": "list",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
}

{
  "operation": "run",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
  "detector_name": "node-health-detector",
  "start_time": "2025-01-15T10:00:00Z",
  "end_time": "2025-01-15T12:00:00Z"
}

{
  "args": "get pods -n kube-system -o wide"
}

How to install

Prerequisites

1. Set up Azure CLI and authenticate:

bash az login

VS Code with GitHub Copilot (Recommended)

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

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

💡 Benefits: The AKS extension handles binary downloads, updates, and configuration automatically, ensuring you always have the latest version with optimal settings.

Alternative Installation Methods

# Download binary and create VS Code configuration
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

# Download binary and create VS Code configuration
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

{
  "servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<enter the file path>",
      "args": []
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<enter the file path>",
      "args": []
    }
  }
}

Other MCP-Compatible Clients

{
  "mcpServers": {
    "aks": {
      "command": "<path of binary aks-mcp>",
      "args": []
    }
  }
}

# Run the server directly
./aks-mcp

Options

Command line arguments:

Usage of ./aks-mcp:
      --access-level string       Access level (readonly, readwrite, admin) (default "readonly")
      --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
      --allow-namespaces string   Comma-separated list of allowed Kubernetes namespaces (empty means all namespaces)
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317)
      --timeout int               Timeout for command execution in seconds, default is 600s (default 600)
      --log-level string          Log level (debug, info, warn, error) (default "info")

Environment variables: - USE_LEGACY_TOOLS: Set to true to use legacy specialized tools instead of unified tools (default: false) - false (default): Uses call_az for Azure operations and call_kubectl for Kubernetes operations - true: Uses legacy tools like az_aks_operations, az_compute_operations, and specialized kubectl tools - Standard Azure authentication environment variables are supported (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID)

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

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:

make help

Quick Start

# 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

# Install dependencies
make deps

# Build and run with --help
make run

# Clean build artifacts
make clean

# Install binary to GOBIN
make install

Manual Build

If you prefer to build without the Makefile:

go build -o aks-mcp ./cmd/aks-mcp

Usage

Ask any questions about your AKS clusters in your AI client, for example:

List all my AKS clusters in my subscription xxx.

What is the network configuration of my AKS cluster?

Show me the network security groups associated with my cluster.

Create a new Azure Fleet named prod-fleet in eastus region.

List all members in my fleet.

Create a placement to deploy nginx workloads to clusters with app=frontend label.

Show me all ClusterResourcePlacements in my fleet.

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 [email protected] 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.