Managing EKS Clusters with Amazon Q and the EKS MCP Server in Your IDE

Overview

The Amazon EKS MCP Server is an open-source tool that integrates Amazon Q Developer with your EKS environment. It translates natural language prompts into AWS and Kubernetes API calls, providing real-time insights into cluster status, logs, and events, enhancing development and operational workflows.

---

The Problem

Managing EKS clusters often involves context-switching between the AWS Management Console, CLI tools like kubectl or eksctl, and writing Infrastructure as Code (IaC). This disrupts productivity. While generative AI can produce Kubernetes manifests or IaC templates, it often lacks real-time awareness of your EKS environment, leading to generic or outdated outputs.

---

The Solution: The Amazon EKS MCP Server

The EKS MCP Server is a lightweight, local tool that runs in your IDE via Amazon Q. It leverages the AWS Labs EKS MCP Server (awslabs.eks-mcp-server) to interact with EKS and Kubernetes APIs, enabling context-aware management through natural language.

---

Key Features

• Conversational Management: Create, describe, update, or delete EKS clusters and Kubernetes resources using English prompts.
• Environment Discovery: Query active EKS clusters, nodes, pods, or other resources (e.g., "list all pods in my cluster").
• Troubleshooting Support: Retrieve logs, events, or search the EKS Troubleshoot Guide (e.g., "why is my pod crashing?").
• Manifest and Template Generation: Generate Kubernetes manifests or CloudFormation templates based on interactions.
• Secure Operations: Uses AWS authentication and Kubernetes RBAC, with configurable read-only modes.

---

Prerequisites

• Python 3.10+: Install Python 3.10 or higher (python.org or brew install python@3.10 on macOS).

• uv Package Manager: Install uv to use the uvx command (brew install uv on macOS or follow instructions).

• AWS CLI: Install and configure with credentials (aws configure) or set environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION).

• IAM Permissions: Attach the following policies to your IAM user or role:

  • Read-Only Operations:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "eks:DescribeCluster",
                    "cloudformation:DescribeStacks",
                    "cloudwatch:GetMetricData",
                    "logs:StartQuery",
                    "logs:GetQueryResults",
                    "iam:GetRole",
                    "iam:GetRolePolicy",
                    "iam:ListRolePolicies",
                    "iam:ListAttachedRolePolicies",
                    "iam:GetPolicy",
                    "iam:GetPolicyVersion"
                ],
                "Resource": "*"
            }
        ]
    }

  • Write Operations (use only in trusted environments):

    For write operations, we recommend the following IAM policies to ensure successful deployment of EKS clusters using the CloudFormation template in /awslabs/eks_mcp_server/templates/eks-templates/eks-with-vpc.yaml:

    • IAMFullAccess: Enables creation and management of IAM roles and policies required for cluster operation
    • AmazonVPCFullAccess: Allows creation and configuration of VPC resources including subnets, route tables, internet gateways, and NAT gateways
    • AWSCloudFormationFullAccess: Provides permissions to create, update, and delete CloudFormation stacks that orchestrate the deployment
    • EKS Full Access (provided below): Required for creating and managing EKS clusters, including control plane configuration, node groups, and add-ons

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": "eks:*",
                  "Resource": "*"
              }
          ]
      }

    Important Security Note: Users should exercise caution when --allow-write and --allow-sensitive-data-access modes are enabled with these broad permissions, as this combination grants significant privileges to the MCP server. Only enable these flags when necessary and in trusted environments. For production use, consider creating more restrictive custom policies.

  Example of the user/role with Read & Write access:

• Kubernetes API Access:

  • Your IAM principal must have created the EKS cluster or have an EKS Access Entry configured (aws eks create-access-entry --cluster-name <name> --principal-arn <your-arn>).
  • Configure kubectl:

    aws eks update-kubeconfig --name <cluster-name> --region us-west-2

• IDE with Amazon Q: Use Visual Studio Code or JetBrains with the latest AWS Toolkit and Amazon Q extension installed.

---

Configuration Steps

Follow these steps to configure the EKS MCP Server in Visual Studio Code.

1. Open MCP Server Settings:

   • Open VS Code and access the sidebar (Ctrl+B or Cmd+B).
   • Click the AWS Toolkit icon (AWS logo) in the sidebar.
   • In the AWS Toolkit panel, select the Amazon Q Chat tab.
   • Click the tools icon (gear or wrench) to open the MCP Servers configuration screen.

2. Add a New Server:

   • Click the plus (+) icon to add a new MCP server.

   • Configure the following:

     • Scope: Select "Global" for all projects or "This workspace" for the current workspace.
     • Name: EKSMCPserver
     • Transport: stdio (only supported protocol).
     • Command: uvx
     • Arguments:
       • Add: awslabs.eks-mcp-server@latest
       • (Optional for safety): Add --allow-write only for write operations.
     • Environment Variables:
       • Add AWS_PROFILE with your profile name (e.g., default), or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

   • Click Save.

   • This generates the following JSON in ~/.aws/amazonq/mcp.json (global) or .amazonq/mcp.json (workspace):

     {
       "mcpServers": {
         "awslabs.eks-mcp-server": {
           "command": "uvx",
           "args": [
             "awslabs.eks-mcp-server@latest",
             "--allow-write",
             "--allow-sensitive-data-access"
           ],
           "env": {
             "FASTMCP_LOG_LEVEL": "ERROR",
             "AWS_PROFILE": "default",
             "AWS_REGION": "us-west-2"
           },
           "autoApprove": [],
           "disabled": false
         }
       }
     }
     

   • If you see: MCP: server 'EKSMCPserver' failed to connect: Command 'uvx' not found

     Install uv (brew install uv) and verify with `uvx --version

3. Verifying the connection:

   • After saving, Amazon Q displays the server’s tools (e.g., manage_eks_staks, list_k8s_resources, get_pod_logs etc). All the list of available tools can be found at - https://awslabs.github.io/mcp/servers/eks-mcp-server/#tools

---

Usage Examples

> List the Clusters

> Lists all available API versions in the specified Kubernetes cluster

> Create Cluster

---

Best Practices and Security

• Read-Only Mode: Omit --allow-write and --allow-sensitive-data-access for inspection tasks. Create a separate server configuration for write operations.
• Least Privilege: Use the read-only IAM policy for daily tasks. Restrict write policies (IAMFullAccess, AmazonVPCFullAccess, etc.) to sandbox environments.
• Sensitive Data: Avoid including secrets in prompts or generated files. Do not use the server to create Kubernetes Secrets.
• New Conversations: Start a new Amazon Q chat for clean operations to avoid history influencing results.
• CloudTrail Auditing: Enable CloudTrail to track API calls.
• IAM Access Analyzer: Review and remove unused permissions regularly.
• Kubernetes Access: Ensure your IAM principal has an EKS Access Entry or created the cluster to avoid authorization errors.

---

Limitations and Considerations

• API Support: Limited to EKS and Kubernetes resources supported by AWS SDK and Kubernetes APIs. Verify regional availability.
• Complex Dependencies: Creating clusters with dependencies (e.g., VPCs, subnets) may require multiple prompts.
• Performance: Dependent on AWS and Kubernetes API response times. Large operations may hit rate limits.
• Template Output: Generated templates are for importing existing resources and may need manual edits for new deployments.

---

Conclusion

The Amazon EKS MCP Server, sourced from https://awslabs.github.io/mcp/servers/eks-mcp-server/, enables AI-driven, conversational management of EKS clusters within your IDE. It boosts productivity by integrating real-time context and automation, simplifying Kubernetes workflows on AWS.

---

References

• AWS Labs EKS MCP Server: https://awslabs.github.io/mcp/servers/eks-mcp-server/
• Amazon Q: https://docs.aws.amazon.com/amazonq/