EKS MCP Server - Setup Guide

EKS MCP Server - Setup Guide

Overview

The EKS MCP Server is a Model Context Protocol (MCP) server that provides programmatic access to Amazon EKS (Elastic Kubernetes Service) clusters. It allows you to interact with Kubernetes resources through the MCP interface, enabling integration with AI assistants and other applications.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that allows applications to provide context and tools to large language models. This server implements the MCP protocol to expose Kubernetes operations as callable tools.

Prerequisites

Before setting up the EKS MCP server, ensure you have the following installed:

Required Software

1. Node.js (v18.0.0 or higher)

   • Download: https://nodejs.org/
   • Verify: node --version

2. npm (comes with Node.js)

   • Verify: npm --version

3. kubectl (Kubernetes command-line tool)

   • Installation: https://kubernetes.io/docs/tasks/tools/install-kubectl/
   • Verify: kubectl version --client

4. AWS CLI (for EKS cluster access)

   • Installation: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
   • Verify: aws --version

AWS Configuration

1. AWS Credentials

   • Configure AWS credentials: aws configure
   • Provide Access Key ID and Secret Access Key
   • Set default region: ap-northeast-2 (or your cluster region)

2. EKS Cluster Access

   • Ensure you have permissions to access the EKS cluster
   • Update kubeconfig:

     aws eks update-kubeconfig --region ap-northeast-2 --name Shared-cluster
     

3. Verify kubectl Access

   • List available contexts: kubectl config get-contexts
   • Verify cluster connection: kubectl get nodes

Installation

Step 1: Clone or Navigate to Repository

cd c:\Users\ashut\OneDrive\Desktop\Kalyani\Git\eks-mcp-server

Step 2: Install Dependencies

npm install

This will install:

• @kubernetes/client-node - Kubernetes client library
• @modelcontextprotocol/sdk - MCP SDK for Node.js

Step 3: Verify Installation

Verify that all dependencies are installed correctly:

npm list

You should see:

[email protected]
├── @kubernetes/client-node@^1.4.0
└── @modelcontextprotocol/sdk@^1.26.0

Configuration

EKS Cluster Configuration

The server automatically loads your kubeconfig from the default location:

• Linux/macOS: ~/.kube/config
• Windows: %USERPROFILE%\.kube\config

Configure Kubeconfig for EKS

1. Add EKS cluster to kubeconfig:

   aws eks update-kubeconfig --region ap-northeast-2 --name Shared-cluster --profile <your-aws-profile>
   

2. Verify context:

   kubectl config get-contexts
   

3. Switch to EKS context (if needed):

   kubectl config use-context eks-bastion
   

MCP Server Configuration

The server is configured in server.js with the following defaults:

• Server Name: eks-mcp-server
• Version: 1.0.0
• Transport: Stdio (standard input/output)
• Capabilities: Tools

Registering with MCP Clients

To use this server with an MCP client (e.g., Claude Desktop), configure it in your MCP client settings:

For Claude Desktop (~/AppData/Roaming/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "eks-mcp-server": {
      "command": "node",
      "args": ["c:\\Users\\ashut\\OneDrive\\Desktop\\Kalyani\\Git\\eks-mcp-server\\server.js"],
      "env": {
        "KUBECONFIG": "C:\\Users\\ashut\\.kube\\config"
      }
    }
  }
}

Available Tools

1. list_pods

Lists all pods across all namespaces in the cluster.

Input: None

Output: JSON array of pod names

Example:

kubectl --context="eks-bastion" get pods --all-namespaces

Running the Server

Start the Server

node server.js

You should see output indicating the server is running:

[Listening on stdio]

Server will Wait for Commands

Once started, the server listens for MCP protocol commands from clients and executes them based on the requested tool.

Stop the Server

Press Ctrl+C to stop the server.

Demo & Usage Examples

Demo 1: List All Pods in the Cluster

Objective: Get a list of all pods running in the Shared-cluster

Manual kubectl Command:

kubectl --context="eks-bastion" get pods --all-namespaces -o wide

Expected Output (Tabular Format):

NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE     IP              NODE
default       nginx-7c5d8bf9f7-7hkz5                   1/1     Running   0          2m      12.0.13.64      ip-12-0-13-242.ap-northeast-2.compute.internal
kube-system   aws-node-l5rdc                           2/2     Running   0          6h53m   12.0.13.242     ip-12-0-13-242.ap-northeast-2.compute.internal
kube-system   aws-node-msjfh                           2/2     Running   0          6h53m   12.0.11.88      ip-12-0-11-88.ap-northeast-2.compute.internal
kube-system   coredns-7dc8bfcfff-mgzh5                1/1     Running   0          6h54m   12.0.11.166     ip-12-0-11-88.ap-northeast-2.compute.internal
kube-system   coredns-7dc8bfcfff-zw69f                1/1     Running   0          6h54m   12.0.11.207     ip-12-0-11-88.ap-northeast-2.compute.internal
kube-system   kube-proxy-hfvxb                         1/1     Running   0          6h53m   12.0.13.242     ip-12-0-13-242.ap-northeast-2.compute.internal
kube-system   kube-proxy-qqzwq                         1/1     Running   0          6h53m   12.0.11.88      ip-12-0-11-88.ap-northeast-2.compute.internal

Demo 2: List Cluster Nodes

Objective: View all nodes in the Shared-cluster

Command:

kubectl --context="eks-bastion" get nodes -o wide

Expected Output:

NAME                                             STATUS   ROLES    AGE     VERSION               INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                      KERNEL-VERSION                    CONTAINER-RUNTIME
ip-12-0-11-88.ap-northeast-2.compute.internal    Ready    <none>   6h51m   v1.34.2-eks-ecaa3a6   12.0.11.88    <none>        Amazon Linux 2023.10.20260120  6.12.64-87.122.amzn2023.x86_64   containerd://2.1.5
ip-12-0-13-242.ap-northeast-2.compute.internal   Ready    <none>   6h51m   v1.34.2-eks-ecaa3a6   12.0.13.242   <none>        Amazon Linux 2023.10.20260120  6.12.64-87.122.amzn2023.x86_64   containerd://2.1.5

Demo 3: Check Pod Status in Specific Namespace

Objective: Monitor pods in the default namespace

Command:

kubectl --context="eks-bastion" get pods -n default -w

Output:

NAME                     READY   STATUS    RESTARTS   AGE
nginx-7c5d8bf9f7-7hkz5   1/1     Running   0          5m

Demo 4: Describe a Pod

Objective: Get detailed information about a specific pod

Command:

kubectl --context="eks-bastion" describe pod nginx-7c5d8bf9f7-7hkz5 -n default

Demo 5: View Pod Logs

Objective: Inspect logs from a running pod

Command:

kubectl --context="eks-bastion" logs nginx-7c5d8bf9f7-7hkz5 -n default

Troubleshooting

Issue 1: "context was not found for specified context: Shared-cluster"

Cause: The kubeconfig doesn't have a context named "Shared-cluster"

Solution:

1. Check available contexts:

   kubectl config get-contexts
   

2. Use the correct context name (e.g., eks-bastion):

   kubectl --context="eks-bastion" get nodes
   

3. If context doesn't exist, update kubeconfig:

   aws eks update-kubeconfig --region ap-northeast-2 --name Shared-cluster
   

Issue 2: "Unable to connect to the server"

Cause: No network connectivity to the EKS cluster

Solution:

1. Verify AWS credentials are configured:

   aws sts get-caller-identity
   

2. Check if cluster is running and accessible
3. Verify security groups allow your IP to access the cluster

Issue 3: "Permission denied" errors

Cause: AWS user/role doesn't have permissions for the cluster

Solution:

1. Verify IAM permissions for EKS access
2. Check if user is in the cluster's aws-auth ConfigMap:

   kubectl --context="eks-bastion" get configmap -n kube-system aws-auth -o yaml
   

Issue 4: Pod in CrashLoopBackOff status

Cause: Application inside the pod is crashing on startup

Solution:

1. Check pod logs:

   kubectl --context="eks-bastion" logs <pod-name> -n <namespace>
   

2. Describe the pod:

   kubectl --context="eks-bastion" describe pod <pod-name> -n <namespace>
   

3. Check image is correct:

   kubectl --context="eks-bastion" get pod <pod-name> -n <namespace> -o yaml | grep image
   

4. Fix the issue (e.g., correct the image name):

   kubectl --context="eks-bastion" set image deployment/<deployment-name> <container-name>=<correct-image> -n <namespace>
   

Issue 5: ImagePullBackOff error

Cause: Container image cannot be pulled from the registry

Solution:

1. Verify the image exists and is spelled correctly:

   docker pull <image-name>
   

2. Check if using private registry, ensure imagePullSecrets are configured
3. Update the deployment with correct image:

   kubectl --context="eks-bastion" set image deployment/<deployment-name> <container-name>=<correct-image> -n <namespace>
   

Full Workflow Example

Scenario: Deploy nginx and fix a failing pod

Step 1: List current pods

kubectl --context="eks-bastion" get pods -n default

Step 2: Check pod status

kubectl --context="eks-bastion" get pods --all-namespaces | findstr "CrashLoopBackOff"

Step 3: Describe the failing pod

kubectl --context="eks-bastion" describe pod nginx-66686b6766-tdzrb -n default

Step 4: Check pod logs

kubectl --context="eks-bastion" logs nginx-66686b6766-tdzrb -n default --tail=50

Step 5: Fix the issue (e.g., update the image)

kubectl --context="eks-bastion" set image deployment/nginx nginx=nginx:latest -n default

Step 6: Monitor pod restart

kubectl --context="eks-bastion" get pods -n default -w

Step 7: Verify pod is running

kubectl --context="eks-bastion" get pods -n default

Quick Reference Commands

Next Steps

1. Extend the Server: Add more tools to interact with deployments, services, etc.
2. Production Deployment: Configure the server for production use with proper authentication and error handling
3. Integration: Connect the server to your MCP client for AI-assisted Kubernetes management

References

• Model Context Protocol Documentation
• Kubernetes Python Client
• AWS EKS Documentation
• kubectl Documentation

Last Updated: February 7, 2026 Version: 1.0.0