Kubernetes AI助手MCP服务

Prerequisites

1. Set up Azure CLI and authenticate:

   az login
   

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.

Install dependencies

make deps

How to install

Deploy the MCP server in-cluster (Remote MCP)

<details> <summary> Remote MCP Installation </summary> To enable the remote AKS MCP server in your AKS cluster, see the instructions below:

1. Helm chart installation with OAuth-based access: Helm Chart

2. Helm chart installation with RBAC (Workload Identity): Blog Post - Deploy AKS MCP server with Workload Identity </details>

Enable AKS-MCP server in Docker MCP Gateway

docker mcp server enable aks

Note: You still need to configure the server (e.g. using `docker mcp config`) with your Azure credentials, kubeconfig file, and access level.

#### 🐋 Containerized MCP configuration

For containerized deployment, you can run AKS-MCP server using the official Docker image:

Option A: Mount credentials from host (recommended):

Option B: fetch the credentials inside the container:

Start the MCP server container first per above command, and then run the following commands to fetch the credentials: - Login to Azure CLI: docker exec -it <container-id> az login --use-device-code - Get kubeconfig: docker exec -it <container-id> az aks get-credentials -g <resource-group> -n <cluster-name>

Note that:

• Host Azure CLI logins don’t automatically propagate into containers without mounting ~/.azure.
• User ID should be set for option A, orelse the mcp user inside container won't be able to access the mounted files.

🤖 Custom MCP Client Installation

You can configure any MCP-compatible client to use the AKS-MCP server by running the binary directly:

```bash

🔧 Manual Binary Installation

For direct binary usage without package managers:

1. Download the latest release from the releases page 2. Extract the binary to your preferred location 3. Make it executable (on Unix systems):

   chmod +x aks-mcp
   

</details>

Building from Source

This project includes a Makefile for convenient development, building, and testing. To see all available targets:

make help

Quick Start

```bash

Build the binary

make build

Build for all platforms

make release

#### Common Development Tasks

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.

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

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)

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

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

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

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

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.

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)

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).
2. Search for Azure Kubernetes Service.
3. 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",
        "--transport",
        "stdio"
      ]
    }
  }
}

🐧 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 --transport stdio"
      ]
    }
  }
}

🔧 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:

Step 2: Configure VS Code

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

Option A: Automated Setup Script

For quick setup, you can use these one-liner scripts that download the binary and create the configuration:

Windows (PowerShell):

```powershell

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=@("--transport","stdio")}}} | ConvertTo-Json -Depth 3 | Out-File ".vscode/mcp.json" -Encoding UTF8

*macOS/Linux (Bash):*

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":["--transport","stdio"]}}}' > .vscode/mcp.json

##### Option B: Manual Configuration

> **✨ Simple Setup**: Download the binary for your platform, then use the manual configuration below to set up the MCP server in VS Code.

#### Manual VS Code Configuration

You can configure the AKS-MCP server in two ways:

**1. Workspace-specific configuration** (recommended for project-specific usage):

Create a `.vscode/mcp.json` file in your workspace with the path to your downloaded binary:

**2. User-level configuration** (persistent across all workspaces):

For a persistent configuration that works across all your VS Code workspaces, add the MCP server to your VS Code user settings:

1. Open VS Code Settings (Ctrl+, or Cmd+,)
2. Search for "mcp" in the settings
3. Add the following to your User Settings JSON:

Step 3: Load the AKS-MCP server tools to Github Copilot

1. If running on an older version of VS Code: restart VS Code i.e. close and reopen VS Code to load the new MCP server configuration. 2. Open GitHub Copilot in VS Code and switch to Agent mode 3. Click the Tools button or run /list in the Github Copilot window to see the list of available tools 4. You should see the AKS-MCP tools in the list 5. Try a prompt like: "List all my AKS clusters in subscription xxx" 6. 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.

</details>