Skip to main content

Access Teleport Kubernetes clusters over MCP

Report an Issue

Did you know? MCP access is part of a broader Agentic Identity Framework.

The Agentic Identity Framework is a standards-driven set of designs, SDKs, and reference implementations for deploying AI agents securely.

Explore framework

This guide shows you how to connect to Teleport Kubernetes clusters with MCP clients.

Prerequisites​

  • A running Teleport cluster accessible at a hostname with a valid TLS certificate. 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.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tsh client reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • Kubernetes Clusters enrolled with Teleport. See our guides.
Headless and automated environments

This guide uses interactive tsh login. For headless environments, CI/CD pipelines, or automation, use Machine ID (tbot) to issue short-lived credentials without interactive authentication.

Step 1/2. List available MCP servers​

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.

Step 2/2. Configure MCP clients​

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

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:

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