Skip to main content
Version: 19.x (unreleased)

Access Teleport Kubernetes clusters over MCP

Report an issue with this page

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 for a free trial or set up a demo environment.

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

      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.

  • Kubernetes Clusters enrolled with Teleport. See our guides.

Step 1/2. Configure MCP clients​

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

tsh login --proxy=teleport.example.com:443 [email protected]

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 our 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 MCP server.

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"
      ]
    }
  }
}

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

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

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

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