# Access Teleport Kubernetes clusters over MCP

This guide explains how to connect to Teleport Kubernetes Clusters with MCP clients.

## Prerequisites

- A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- The `tsh` client.

  Installing `tsh` client

  1. Determine the version of your Teleport cluster. The `tsh` client must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tsh` client:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tsh` client:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tsh` client to your %PATH%
     NOTE: Do not place the `tsh` client in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tsh` client. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* Kubernetes Clusters enrolled with Teleport. See our [guides](https://goteleport.com/docs/enroll-resources/kubernetes-access/getting-started.md).

## Step 1/2. Configure MCP clients

First, sign in into your Teleport cluster using `tsh login`:

```
$ tsh login --proxy=teleport.example.com:443 --user=myuser@example.com
```

To list Kubernetes clusters available for you to access:

```
$ tsh kube ls
Kube Cluster Name Labels  Selected
----------------- ------- --------
minikube          env=dev *
```

Now log in to your Kubernetes cluster, replacing minikube with your Kubernetes cluster name:

```
$ tsh kube login minikube
Logged into Kubernetes cluster "minikube". Try 'kubectl version' to test the connection.
```

This command also updates your default Kubernetes config.

Next, configure your MCP clients to use the [`kubernetes-mcp-server`](https://github.com/containers/kubernetes-mcp-server) MCP server.

**Claude Desktop**

Open your `claude_desktop_config.json` and add the MCP server to the list of mcpServers:

```
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ]
    }
  }
}

```

**Cursor**

You can install the extension by editing the `mcp.json` file:

```
{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

```

**VS Code / VS Code Insiders**

You can install the extension by running the following command:

```
For VS Code
code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'
For VS Code Insiders
code-insiders --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'
```

## Step 2/2. Access Teleport-protected resources over MCP

After configuring your MCP client, you will find Kubernetes and Helm tools from `kubernetes-mcp-server`.

You can now use these tools to interact with your Kubernetes clusters via Teleport in your MCP clients:

![Kube usage context](/docs/assets/images/usage-kube-context-3775465a51b31b13247614402a37f660.png) ![Kube usage pod](/docs/assets/images/usage-kube-pod-787be32e37941533dfcc6e6a1795dd09.png)

## Teleport behind TLS-terminating load balancers

If your Teleport cluster is behind a TLS-terminating load balancer or reverse proxy, you can start a local proxy with `tsh`:

```
$ tsh proxy kube -p 8888
```

Copy the `KUBECONFIG` path from the output of the command, and add it with the `--kubeconfig` flag in your MCP client configuration. For example:

```
{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest", "--kubeconfig", "/path/to/your/tsh/localproxy-8888-kubeconfig"]
    }
  }
}

```

Alternatively, you can use [Teleport Connect](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md) to run the local proxy to your Kubernetes cluster. You can find the `KUBECONFIG` path from the terminal in Teleport Connect:

```
$ echo $KUBECONFIG
/path/to/your/minikube-kubeconfig
```