# EKS Metrics MCP Server

Python MCP server for querying Amazon EKS cluster metrics.

Implemented now:

- Kubernetes API server `/metrics`, equivalent to `kubectl get --raw /metrics`
- Metric filtering by exact metric name, metric name regex, and labels
- A source selector that currently supports `api_server` and reserves `cloudwatch`

CloudWatch metric collection is intentionally left as a future extension.

## Install

```bash
python3.11 -m pip install -e .
```

The MCP Python SDK requires Python 3.10 or newer. If `python` points to Python
3.9, use `python3.11` or another Python 3.10+ interpreter in both installation
and MCP client configuration.

The server uses the Kubernetes Python client. Authentication follows the same
configuration sources as `kubectl`:

- In-cluster service account credentials when running inside Kubernetes
- Local kubeconfig from `KUBECONFIG` or `~/.kube/config`
- Optional per-call `kube_context` and `kubeconfig_path` tool arguments

The Kubernetes identity must be allowed to call the API server non-resource URL
`/metrics`.

## Run

```bash
eks-metrics-mcp-server
```

or:

```bash
python3.11 -m eks_metrics_mcp_server.server
```

## Codex MCP config

```toml
[mcp_servers.eks-metrics]
enabled = true
command = "python3.11"
args = ["-m", "eks_metrics_mcp_server.server"]
cwd = "/root/eks-metrics-server/eks-metrics-mcp-server"

[mcp_servers.eks-metrics.env]
PYTHONPATH = "/root/eks-metrics-server/eks-metrics-mcp-server/src"
```

## MCP Tools

### `get_eks_metrics`

Fetch metrics from the selected source.

Important arguments:

- `source`: `api_server` or `cloudwatch`; only `api_server` is implemented
- `metric_name`: exact Prometheus metric name
- `metric_name_pattern`: regular expression for metric names
- `label_selectors`: label key/value filters
- `limit`: maximum returned samples
- `include_raw`: include original Prometheus sample line
- `kube_context`: kubeconfig context to use
- `kubeconfig_path`: kubeconfig path to use

Example metric names from Kubernetes API server metrics include
`apiserver_request_total`, `apiserver_request_duration_seconds_bucket`, and
`apiserver_current_inflight_requests`.

### `list_api_server_metric_names`

Return metric names available from `/metrics`, including type/help metadata and
sample counts.

## Kubernetes RBAC

For an in-cluster deployment, bind a service account to a role that can read
the `/metrics` non-resource URL:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks-metrics-mcp-api-server-metrics
rules:
  - nonResourceURLs:
      - /metrics
    verbs:
      - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks-metrics-mcp-api-server-metrics
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks-metrics-mcp-api-server-metrics
subjects:
  - kind: ServiceAccount
    name: eks-metrics-mcp
    namespace: default
```