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.
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.
星數
146
工具
—
可用率
—
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:
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
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
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
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
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:
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).
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:
Tool:call_az(default, available when USE_LEGACY_TOOLS is not set or set to false)
Unified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.
Parameters:
cli_command: The complete Azure CLI command to execute (e.g., az aks list --resource-group myRG, az vm list --subscription <sub-id>)
timeout: Optional timeout in seconds (default: 120)
Example Usage:
{
"cli_command": "az aks list --resource-group myResourceGroup --output json"
}
Access Control:
readonly: Only read operations are allowed
readwrite/admin: Both read and write operations are allowed
Important: Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).
Tool:az_aks_operations(available when USE_LEGACY_TOOLS=true)
Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.
Available Operations:
Read-Only (all access levels):
show: Show cluster details
list: List clusters in subscription/resource group
Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
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:
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
💡 Benefits: The AKS extension handles binary downloads, updates, and configuration automatically, ensuring you always have the latest version with optimal settings.
Alternative Installation Methods
Step 1: Download the Binary
Choose your platform and download the latest AKS-MCP binary:
Click the Tools button or run /list in the Github Copilot window to see the list of available tools
You should see the AKS-MCP tools in the list
Try a prompt like: "List all my AKS clusters in subscription xxx"
The agent will automatically use AKS-MCP tools to complete your request
💡 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.
Note: Ensure you have authenticated with Azure CLI (az login) for the server to access your Azure resources.
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 Make4.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.
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
Prerequisites: Go ≥ 1.24.x, Azure CLI, Git
Setup: Fork the repo, clone locally, run make deps && make build
Test: Run make test and make check
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 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.
A
Aks
Azure·146 顆星·
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.
上次檢查時間:2026-11-15。 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.