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

Step 2: Install Dependencies

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:

You should see:

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

Available Tools

1. list_pods

Lists all pods across all namespaces in the cluster.

Input: None

Output: JSON array of pod names

Example:

Running the Server

Start the Server

You should see output indicating the server is running:

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:

Expected Output (Tabular Format):

Demo 2: List Cluster Nodes

Objective: View all nodes in the Shared-cluster

Command:

Expected Output:

Demo 3: Check Pod Status in Specific Namespace

Objective: Monitor pods in the default namespace

Command:

Output:

Demo 4: Describe a Pod

Objective: Get detailed information about a specific pod

Command:

Demo 5: View Pod Logs

Objective: Inspect logs from a running pod

Command:

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

Step 2: Check pod status

Step 3: Describe the failing pod

Step 4: Check pod logs

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

Step 6: Monitor pod restart

Step 7: Verify pod is running

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