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.

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 with --transport stdio, 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.

If you deploy remotely anyway

The sse and streamable-http transports and the Helm chart exist for specific advanced scenarios, but they move AKS-MCP outside its intended usage. If you use them, you own the resulting risk, and you must at minimum:

• Require authentication. Enable OAuth (see OAuth Authentication). Never expose an unauthenticated endpoint.
• Restrict network exposure. Do not publish the endpoint to the internet or to a shared network. Bind to loopback, or place it behind network policy / private networking so that only intended callers can reach it.
• Minimize the server identity’s permissions. Assume every caller inherits them in full. Use a dedicated, least-privileged identity scoped to a single subscription or resource group — never a broadly privileged one.
• Do not treat it as multi-tenant. AKS-MCP cannot separate one caller’s authority from another’s; all callers share the single server identity.

Browser-originated requests are a particular concern: a malicious web page can attempt to reach a locally or privately bound HTTP endpoint. Authentication and network isolation are the mitigations.

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": [
  "--transport",
  "stdio",
  "--access-level",
  "readwrite"
]

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

How to install

Prerequisites

1. Set up Azure CLI and authenticate:

   az login
   

VS Code with GitHub Copilot (Recommended)

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

Deploy the MCP server in-cluster (Remote MCP)

Outside the supported deployment model. In-cluster / remote deployment is not the intended usage of AKS-MCP and is not hardened for it. Every caller that can reach the endpoint inherits the full Azure and Kubernetes privileges of the server identity. --access-level and the credential-command denylist reduce accidental damage but are not security boundaries against a malicious caller. If you proceed, you must enable OAuth, restrict network reachability, and use a dedicated least-privileged identity. See Supported Deployment Model and Security Considerations.

Alternative Installation Methods

Other MCP-Compatible Clients

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)
      --host string               Host to listen for the server (only used with transport sse or streamable-http) (default "127.0.0.1")
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "")
      --port int                  Port to listen for the server (only used with transport sse or streamable-http) (default 8000)
      --timeout int               Timeout for command execution in seconds, default is 600s (default 600)
      --transport string          Transport mechanism to use (stdio, sse or streamable-http) (default "stdio")
      --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
• 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:

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

Docker

# Build Docker image
make docker-build

# Run Docker container
make docker-run

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.