MCP server
A built-in MCP server that lets external clients manage port-forwards through kftray.
kftray includes a built-in MCP server. When enabled, MCP-compatible clients can browse Kubernetes clusters, start and stop port-forwards, and manage saved configurations, all through the same engine that powers the desktop and terminal interfaces.
Enabling
Open Settings in kftray.
Find the MCP Server section.
Toggle it on and set the port (default: 3000).
The server runs in the background as part of kftray. It stops when kftray closes and auto-starts on next launch if left enabled.
| Setting | Default | Description |
|---|---|---|
| Enabled | false | Whether the MCP server starts with the app |
| Port | 3000 | Port the server listens on |
Connecting a client
Point an MCP client at:
http://localhost:3000/mcpClients that read server definitions from a config file typically need an entry like:
{
"mcpServers": {
"kftray": {
"url": "http://localhost:3000/mcp"
}
}
}Where this file lives depends on the client. Check its documentation.
To verify the server is running:
curl http://localhost:3000/healthWhat it can do
The server exposes 16 tools grouped in three areas.
Cluster browsing lets a client list the available kubeconfig contexts, namespaces within a context, services and pods within a namespace, and ports exposed by a service. If a service is not found when listing ports, kftray falls back to looking at container ports on pods matching that name as a label selector.
Port-forward control lets a client start a forward from a saved config or from scratch by specifying context, namespace, service, and port. It can also stop a specific forward, stop all forwards at once, or list everything that is currently running. When starting a forward without a saved config, kftray creates the config automatically. If the forward fails to start, it cleans up the config so nothing is left behind.
Configuration management lets a client list, inspect, create, update, and delete saved configs. It can also export all configs as JSON or import configs from a JSON string. These are the same configs visible in the desktop and terminal interfaces.
Shared state
All interfaces share the same database at ~/.kftray/kftray.db. A config or forward created through the MCP server shows up in the GUI and TUI, and the other way around.
Examples
These show what a user might ask an MCP client and what kftray does behind the scenes.
Tool reference
Cluster browsing
| Tool | Required args | Returns |
|---|---|---|
list_kube_contexts | context names | |
list_namespaces | context | namespace names |
list_services | context, namespace | service names |
list_pods | context, namespace | pods with name, status, and labels |
list_ports | context, namespace, service | ports with name, number, target port, and protocol |
All tools accept an optional kubeconfig parameter. list_pods also accepts label_selector.
Port-forward control
| Tool | Required args | Returns |
|---|---|---|
start_port_forward | config_id or namespace + remote_port | local port, remote port, config ID |
stop_port_forward | config_id | service name, namespace |
stop_all_port_forwards | count of stopped forwards | |
list_active_port_forwards | list of active forwards with config ID, service, namespace, ports, protocol, alias |
When creating a new forward without config_id, these parameters are also accepted: context, service, target, local_port, protocol (tcp or udp), workload_type (service, pod, or proxy), kubeconfig, alias.
Configuration management
| Tool | Required args | Returns |
|---|---|---|
list_configs | configs with ID, alias, service, namespace, ports, protocol | |
get_config | config_id | full config details |
create_config | context, namespace, remote_port | config ID |
update_config | config_id | success status |
delete_config | config_id | success status |
export_configs | all configs as JSON | |
import_configs | configs_json | success status |
Security
Local only by default
The server binds to 127.0.0.1. Only processes on the same machine can reach it.
The MCP server uses the same kubeconfig credentials as the rest of kftray. It does not store or transmit credentials separately.