**Help improve this page** 

To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page.

# Getting Started with the Amazon EKS MCP Server
Get started

This guide walks you through the steps to setup and use the EKS MCP Server with your AI code assistants. You’ll learn how to configure your environment, connect to the server, and start managing your EKS clusters through natural language interactions.

**Note**  
The Amazon EKS MCP Server is in preview release for Amazon EKS and is subject to change.

## Prerequisites


Before you start, make sure you have performed the following tasks:
+  [Create an Amazon account with access to Amazon EKS](https://www.amazonaws.cn/resources/create-account/) 
+  [Install and configure the Amazon CLI with credentials](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-configure.html) 
+  [Install Python 3.10\$1](https://www.python.org/downloads/release/python-3100/) 
+  [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) 

## Setup


### 1. Verify prerequisites


```
# Check that your Python version is 3.10 or higher
python3 --version

# Check uv installation
uv --version

# Verify CLI configuration
aws configure list
```

### 2. Setup IAM permissions


To connect to the EKS MCP server, your [IAM role](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles.html) must have the following policies attached: ** `eks-mcp:InvokeMcp` ** (required permissions for initialization and retrieving information about available tools), ** `eks-mcp:CallReadOnlyTool` ** (required permissions for usage of read only tools), and ** `eks-mcp:CallPrivilegedTool` ** (required permissions for usage of full access (write) tools). These `eks-mcp` permissions are included in the read-only and full-access Amazon managed policies provided, below.
+ Open the [IAM console](https://console.amazonaws.cn/iam/).
+ In the left navigation pane, choose **Users**, **User groups**, or **Roles** depending on the identity you want to attach the policy to, then the name of the specific user, group, or role.
+ Choose the **Permissions** tab.
+ Choose **Attach policies** (or **Add permissions** if it’s the first time).
+ In the policy list, search for and select the managed policy you want to attach:
+  **Read-only operations**: AmazonEKSMCPReadOnlyAccess
+ Choose **Attach policies** (or **Next** and then **Add permissions** to confirm).

This attaches the policy, and the permissions take effect immediately. You can attach multiple policies to the same identity, and each can contain various permissions. To learn more about these policies, see [Amazon managed policies for Amazon Elastic Kubernetes Service](https://docs.amazonaws.cn/eks/latest/userguide/security-iam-awsmanpol.html).

### 3. Choose an AI assistant


Choose one of the following MCP-compatible AI assistants or any MCP-compatible tool:
+  [Install Amazon Q Developer CLI](https://docs.amazonaws.cn/amazonq/latest/qdeveloper-ug/command-line-installing.html) 
+  [Install Kiro](https://kiro.dev/docs/getting-started/installation/) 
+  [Install Cursor](https://cursor.com/download) 
+  [Install Cline VS Code Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) 

## Step 1: Configure your AI assistant


Choose from any one of the following options to setup your AI code assistant. Completing this step sets up your AI code assistant to use the MCP Proxy for Amazon, which is required for secure, authenticated access to the Amazon EKS MCP Server. This involves adding or editing the MCP configuration file (e.g., `~/.aws/amazonq/mcp.json` for Amazon Q Developer CLI). The proxy acts as a client-side bridge, handling Amazon SigV4 authentication using your local Amazon credentials and enabling dynamic tool discovery for interacting with backend Amazon MCP servers like the EKS MCP Server. To learn more, see the [https://github.com/aws/mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws).

### Option A: Amazon Q Developer CLI


The Q Developer CLI provides the most integrated experience with the EKS MCP Server.

#### 1. Locate MCP Configuration File

+  **macOS/Linux**: `~/.aws/q/mcp.json` 
+  **Windows**: `%USERPROFILE%\.aws\q\mcp.json` 

#### 2. Add MCP Server Configuration


Create the configuration file if it doesn’t exist. Be sure to replace the region (`{region}`) placeholder with your desired region.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **Security note**: `--read-only` can be used to only allow read-only tool operations.

#### 3. Verify Configuration


Restart Q Developer CLI, then check available tools:

```
q /tools
```

### Option B: Kiro IDE


Kiro is an AI-first coding workspace with built-in [MCP support](https://kiro.dev/docs/mcp/).

#### 1. Open Kiro Settings

+ Open Kiro
+ Go to **Kiro** → **Settings** and search for "MCP Config"
+ Or press `Cmd+Shift+P,` (Mac) or `Ctrl+Shift+P,` (Windows/Linux) and search for "MCP Config"

#### 2. Add MCP Server Configuration

+ Click "Open Workspace MCP Config" or "Open User MCP Config" to edit the MCP configuration file directly.

Be sure to replace the region (`{region}`) placeholder with your desired region.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **Security note**: `--read-only` can be used to only allow read-only tool operations.

### Option C: Cursor IDE


Cursor provides built-in MCP support with a graphical configuration interface.

#### 1. Open Cursor Settings

+ Open Cursor
+ Go to **Settings** → **Cursor Settings** → **Tools & MCP** 
+ Or press `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows) and search for "MCP"

#### 2. Add MCP Server Configuration

+ Click "New MCP Server"

Create the configuration file if it doesn’t exist. Be sure to replace the region (`{region}`) placeholder with your desired region.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **Security note**: `--read-only` can be used to only allow read-only tool operations.

#### 3. Restart Cursor


Close and reopen Cursor for the changes to take effect.

#### 4. Verify in Cursor chat


Open the chat panel and try:

```
What EKS MCP tools are available?
```

You should see a list of available EKS management tools.

### Option D: Cline (VS Code Extension)


Cline is a popular VS Code extension that brings AI assistance directly into your editor.

#### 1. Open Cline Settings

+ Open Cline
+ Press `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows) and search for "MCP"

#### 2. Add MCP Server Configuration

+ Click "Add Server"
+ Click "Open User Configuration"

Create the configuration file if it doesn’t exist. Be sure to replace the region (`{region}`) placeholder with your desired region.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}
```

 **Security note**: `--read-only` can be used to only allow read-only tool operations.

#### 2. Reload VS Code


Press `Cmd+Shift+P` / `Ctrl+Shift+P` and select "Developer: Reload Window"

#### 3. Verify configuration


Open Cline and ask:

```
List the available MCP tools for EKS
```

## Step 2: (Optional) Create a "write" policy


Optionally, you can create a [customer-managed IAM policy](https://docs.amazonaws.cn/privateca/latest/userguide/auth-CustManagedPolicies.html) that provides full access to the Amazon EKS MCP server. This policy grants permissions to use all tools in the EKS MCP server, including both privileged tools that may involve write operations and read-only tools. Note that high-risk permissions (anything with Delete\$1, or unrestricted IAM resource) are included in this policy, as they’re required for setup/teardown of the cluster resources in the **manage\$1eks\$1stacks** tool.

```
aws iam create-policy \
 --policy-name EKSMcpWriteManagementPolicy \
 --policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"eks:DescribeCluster\", \"eks:ListClusters\", \"eks:DescribeNodegroup\", \"eks:ListNodegroups\", \"eks:DescribeAddon\", \"eks:ListAddons\", \"eks:DescribeAccessEntry\", \"eks:ListAccessEntries\", \"eks:DescribeInsight\", \"eks:ListInsights\", \"eks:AccessKubernetesApi\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"eks:CreateCluster\", \"eks:DeleteCluster\", \"eks:CreateAccessEntry\", \"eks:TagResource\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:GetRole\", \"iam:ListRolePolicies\", \"iam:ListAttachedRolePolicies\", \"iam:GetRolePolicy\", \"iam:GetPolicy\", \"iam:GetPolicyVersion\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:TagRole\", \"iam:CreateRole\", \"iam:AttachRolePolicy\", \"iam:PutRolePolicy\", \"iam:DetachRolePolicy\", \"iam:DeleteRole\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:PassRole\"], \"Resource\": \"*\", \"Condition\": {\"StringEquals\": {\"iam:PassedToService\": [\"eks.amazonaws.com\", \"ec2.amazonaws.com\"]}}}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:CreateVpc\", \"ec2:CreateSubnet\", \"ec2:CreateRouteTable\", \"ec2:CreateRoute\", \"ec2:CreateInternetGateway\", \"ec2:CreateNatGateway\", \"ec2:CreateSecurityGroup\", \"ec2:AttachInternetGateway\", \"ec2:AssociateRouteTable\", \"ec2:ModifyVpcAttribute\", \"ec2:ModifySubnetAttribute\", \"ec2:AllocateAddress\", \"ec2:CreateTags\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:DeleteVpc\", \"ec2:DeleteSubnet\", \"ec2:DisassociateRouteTable\", \"ec2:DeleteRouteTable\", \"ec2:DeleteRoute\", \"ec2:DetachInternetGateway\", \"ec2:DeleteInternetGateway\", \"ec2:DeleteNatGateway\", \"ec2:ReleaseAddress\", \"ec2:DeleteSecurityGroup\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:DescribeVpcs\", \"ec2:DescribeSubnets\", \"ec2:DescribeRouteTables\", \"ec2:DescribeInternetGateways\", \"ec2:DescribeNatGateways\", \"ec2:DescribeAddresses\", \"ec2:DescribeSecurityGroups\", \"ec2:DescribeAvailabilityZones\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"cloudformation:CreateStack\", \"cloudformation:UpdateStack\", \"cloudformation:DeleteStack\", \"cloudformation:DescribeStacks\", \"cloudformation:TagResource\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"sts:GetCallerIdentity\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"logs:StartQuery\", \"logs:GetQueryResults\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"cloudwatch:GetMetricData\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"eks-mcp:*\"], \"Resource\": \"*\"}]}"
```

## Step 3: Verify your setup


### Test connection


Ask your AI assistant a simple question to verify the connection:

```
List all EKS clusters in my {aws} account
```

You should see a list of your EKS clusters.

## Step 4: Run your first tasks


### Example 1: Explore your clusters


```
Show me all EKS clusters and their status
What insights does EKS have about my production-cluster?
Show me the VPC configuration for my staging cluster
```

### Example 2: Check Kubernetes resources


```
Get the details of all the kubernetes resources deployed in my EKS cluster
Show me pods that are not in Running state or pods with any restarts
Get the logs from the aws-node daemonset in the last 30 minutes
```

### Example 3: Troubleshoot issues


```
Why is my nginx-ingress-controller pod failing to start?
Search the EKS troubleshooting guide for pod networking issues
Show me events related to the failed deployment in the staging namespace
```

### Example 4: Create resources (if "write" mode is enabled)


```
Create a new EKS cluster named demo-cluster with VPC and Auto Mode
Deploy my containerized app from ECR to the production namespace with 3 replicas
Generate a Kubernetes deployment YAML for my Node.js app running on port 3000
```

## Common configurations


### Scenario 1: Multiple Amazon profiles


If you work with multiple Amazon accounts, create separate MCP server configurations.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp-prod": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2"
      ]
    },
    "eks-mcp-dev": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp-prod": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2"
      ]
    },
    "eks-mcp-dev": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}
```

### Scenario 2: Read-only for production


Create a read-only configuration for production environments.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp-prod-readonly": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2",
        "--read-only"
      ],
      "autoApprove": [
        "list_k8s_resources",
        "get_pod_logs",
        "get_k8s_events"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp-prod-readonly": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2",
        "--read-only"
      ],
      "autoApprove": [
        "list_k8s_resources",
        "get_pod_logs",
        "get_k8s_events"
      ]
    }
  }
}
```

### Scenario 3: Development with full access


For development environments with full write access.

 **For Mac/Linux:** 

```
{
  "mcpServers": {
    "eks-mcp-dev-full": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}
```

 **For Windows:** 

```
{
  "mcpServers": {
    "eks-mcp-dev-full": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}
```

## Considerations


### Security


Do not pass secrets or sensitive information via allowed input mechanisms:
+ Do not include secrets or credentials in YAML files applied with apply\$1yaml.
+ Do not pass sensitive information directly in the prompt to the model.
+ Do not include secrets in CloudFormation templates or application manifests.
+ Avoid using MCP tools for creating Kubernetes Secrets, as this would require providing the secret data to the model.
+ Avoid logging sensitive information in application logs within Kubernetes pods.

YAML content security:
+ Only use YAML files from trustworthy sources.
+ The server relies on Kubernetes API validation for YAML content and does not perform its own validation.
+ Audit YAML files before applying them to your cluster.

Instead of passing secrets through MCP:
+ Use [Amazon Secrets Manager](https://docs.amazonaws.cn/secretsmanager/latest/userguide/intro.html) or [Parameter Store](https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-parameter-store.html) to store sensitive information.
+ Configure proper Kubernetes RBAC for service accounts.
+ Use IAM roles for service accounts (IRSA) for Amazon service access from pods.

Redaction of sensitive data:
+ The EKS MCP Server automatically redacts common patterns for security tokens, certificates, and other sensitive information in tool responses.
+ Redacted values are replaced with `HIDDEN_FOR_SECURITY_REASONS` to avoid accidentally exposing data to the model.
+ This redaction applies to all tool responses including logs, resource descriptions, and configuration data.

## Next up


For configuration options, see [Amazon EKS MCP Server Configuration Reference](eks-mcp-tool-configurations.md). For a complete list of tools, see [Amazon EKS MCP Server Tools Reference](eks-mcp-tools.md).