# 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: 
     ```bash
     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

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

### Step 2: Install Dependencies

```bash
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:

```bash
npm list
```

You should see:
```
eks-mcp-server@1.0.0
├── @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:**
   ```bash
   aws eks update-kubeconfig --region ap-northeast-2 --name Shared-cluster --profile <your-aws-profile>
   ```

2. **Verify context:**
   ```bash
   kubectl config get-contexts
   ```

3. **Switch to EKS context (if needed):**
   ```bash
   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`):
```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:**
```bash
kubectl --context="eks-bastion" get pods --all-namespaces
```

---

## Running the Server

### Start the Server

```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
kubectl --context="eks-bastion" describe pod nginx-7c5d8bf9f7-7hkz5 -n default
```

### Demo 5: View Pod Logs

**Objective:** Inspect logs from a running pod

#### Command:
```bash
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:
   ```bash
   kubectl config get-contexts
   ```
2. Use the correct context name (e.g., `eks-bastion`):
   ```bash
   kubectl --context="eks-bastion" get nodes
   ```
3. If context doesn't exist, update kubeconfig:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   kubectl --context="eks-bastion" logs <pod-name> -n <namespace>
   ```
2. Describe the pod:
   ```bash
   kubectl --context="eks-bastion" describe pod <pod-name> -n <namespace>
   ```
3. Check image is correct:
   ```bash
   kubectl --context="eks-bastion" get pod <pod-name> -n <namespace> -o yaml | grep image
   ```
4. Fix the issue (e.g., correct the image name):
   ```bash
   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:
   ```bash
   docker pull <image-name>
   ```
2. Check if using private registry, ensure imagePullSecrets are configured
3. Update the deployment with correct image:
   ```bash
   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
```bash
kubectl --context="eks-bastion" get pods -n default
```

#### Step 2: Check pod status
```bash
kubectl --context="eks-bastion" get pods --all-namespaces | findstr "CrashLoopBackOff"
```

#### Step 3: Describe the failing pod
```bash
kubectl --context="eks-bastion" describe pod nginx-66686b6766-tdzrb -n default
```

#### Step 4: Check pod logs
```bash
kubectl --context="eks-bastion" logs nginx-66686b6766-tdzrb -n default --tail=50
```

#### Step 5: Fix the issue (e.g., update the image)
```bash
kubectl --context="eks-bastion" set image deployment/nginx nginx=nginx:latest -n default
```

#### Step 6: Monitor pod restart
```bash
kubectl --context="eks-bastion" get pods -n default -w
```

#### Step 7: Verify pod is running
```bash
kubectl --context="eks-bastion" get pods -n default
```

---

## Quick Reference Commands

| Command | Purpose |
|---------|---------|
| `kubectl config get-contexts` | List all kubeconfig contexts |
| `kubectl config use-context <context>` | Switch to a context |
| `kubectl get nodes` | List all cluster nodes |
| `kubectl get nodes -o wide` | List nodes with detailed info |
| `kubectl get pods --all-namespaces` | List all pods across namespaces |
| `kubectl get pods -n <namespace>` | List pods in specific namespace |
| `kubectl describe pod <pod-name> -n <namespace>` | Get detailed pod info |
| `kubectl logs <pod-name> -n <namespace>` | View pod logs |
| `kubectl logs <pod-name> -n <namespace> --tail=50` | View last 50 lines of logs |
| `kubectl get pods -n <namespace> -w` | Watch pods for changes |
| `kubectl set image deployment/<name> <container>=<image> -n <namespace>` | Update pod image |

---

## 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](https://github.com/modelcontextprotocol/specification)
- [Kubernetes Python Client](https://github.com/kubernetes-client/python)
- [AWS EKS Documentation](https://docs.aws.amazon.com/eks/)
- [kubectl Documentation](https://kubernetes.io/docs/reference/kubectl/)

---

**Last Updated:** February 7, 2026  
**Version:** 1.0.0