testkube-mcp — Claude Code MCP server: what it does, how to install
Connects AI assistants to Testkube to orchestrate automated tests in Kubernetes. Useful when you need to trigger runs and inspect artifacts directly from your editor.
claude mcp add --env TK_ACCESS_TOKEN=<TK_ACCESS_TOKEN> --env TK_ORG_ID=<TK_ORG_ID> --env TK_ENV_ID=<TK_ENV_ID> --env TK_CONTROL_PLANE_URL=<TK_CONTROL_PLANE_URL> --env TK_DASHBOARD_URL=<TK_DASHBOARD_URL> --transport stdio testkube-mcp -- docker run -i --rm -e TK_ACCESS_TOKEN -e TK_ORG_ID -e TK_ENV_ID -e TK_CONTROL_PLANE_URL -e TK_DASHBOARD_URL docker.io/kubeshop/mcp-server:2.14.2What testkube-mcp does
This server connects AI assistants with the Testkube testing platform running in Kubernetes. It enables your coding assistant to trigger test workflows, retrieve execution logs, and inspect cluster resource metrics.
Kubeshop distributes the server as a Docker container image, docker.io/kubeshop/mcp-server:2.14.2, for stdio transport. Alternatively, clients can connect directly via an HTTP endpoint on api.testkube.io.
Without TK_ACCESS_TOKEN and your organization identifiers, API calls will fail. Using the stdio mode requires an active Docker daemon on the host.
What it helps with
- trigger test workflows inside Kubernetes clusters via chat
- retrieve execution logs and test artifacts for debugging
- inspect resource metrics and workflow runs without opening dashboards
Example prompts for the agent
- Show recent Testkube execution results and summarize failed steps.
- Trigger the API test workflow in our staging environment and fetch the logs.
How to install testkube-mcp
1Platform CLI
claude mcp add --env TK_ACCESS_TOKEN=<TK_ACCESS_TOKEN> --env TK_ORG_ID=<TK_ORG_ID> --env TK_ENV_ID=<TK_ENV_ID> --env TK_CONTROL_PLANE_URL=<TK_CONTROL_PLANE_URL> --env TK_DASHBOARD_URL=<TK_DASHBOARD_URL> --transport stdio testkube-mcp -- docker run -i --rm -e TK_ACCESS_TOKEN -e TK_ORG_ID -e TK_ENV_ID -e TK_CONTROL_PLANE_URL -e TK_DASHBOARD_URL docker.io/kubeshop/mcp-server:2.14.2Replace <…> with your own values. 4 more environment variables are in the server README
2Platform CLI: remote server
claude mcp add --transport http testkube-mcp https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcp1Platform CLI
codex mcp add testkube-mcp --env TK_ACCESS_TOKEN=<TK_ACCESS_TOKEN> --env TK_ORG_ID=<TK_ORG_ID> --env TK_ENV_ID=<TK_ENV_ID> --env TK_CONTROL_PLANE_URL=<TK_CONTROL_PLANE_URL> --env TK_DASHBOARD_URL=<TK_DASHBOARD_URL> -- docker run -i --rm -e TK_ACCESS_TOKEN -e TK_ORG_ID -e TK_ENV_ID -e TK_CONTROL_PLANE_URL -e TK_DASHBOARD_URL docker.io/kubeshop/mcp-server:2.14.2Replace <…> with your own values. 4 more environment variables are in the server README
2Platform CLI: remote server
codex mcp add testkube-mcp --url https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcp1Config file
{
"mcpServers": {
"testkube-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TK_ACCESS_TOKEN",
"-e",
"TK_ORG_ID",
"-e",
"TK_ENV_ID",
"-e",
"TK_CONTROL_PLANE_URL",
"-e",
"TK_DASHBOARD_URL",
"docker.io/kubeshop/mcp-server:2.14.2"
],
"env": {
"TK_ACCESS_TOKEN": "<TK_ACCESS_TOKEN>",
"TK_ORG_ID": "<TK_ORG_ID>",
"TK_ENV_ID": "<TK_ENV_ID>",
"TK_CONTROL_PLANE_URL": "<TK_CONTROL_PLANE_URL>",
"TK_DASHBOARD_URL": "<TK_DASHBOARD_URL>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
2Config file
{
"mcpServers": {
"testkube-mcp": {
"url": "https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcp"
}
}
}1Config file
{
"servers": {
"testkube-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TK_ACCESS_TOKEN",
"-e",
"TK_ORG_ID",
"-e",
"TK_ENV_ID",
"-e",
"TK_CONTROL_PLANE_URL",
"-e",
"TK_DASHBOARD_URL",
"docker.io/kubeshop/mcp-server:2.14.2"
],
"env": {
"TK_ACCESS_TOKEN": "<TK_ACCESS_TOKEN>",
"TK_ORG_ID": "<TK_ORG_ID>",
"TK_ENV_ID": "<TK_ENV_ID>",
"TK_CONTROL_PLANE_URL": "<TK_CONTROL_PLANE_URL>",
"TK_DASHBOARD_URL": "<TK_DASHBOARD_URL>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
2Config file
{
"servers": {
"testkube-mcp": {
"type": "http",
"url": "https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcp"
}
}
}1Platform CLI
gemini mcp add -e TK_ACCESS_TOKEN=<TK_ACCESS_TOKEN> -e TK_ORG_ID=<TK_ORG_ID> -e TK_ENV_ID=<TK_ENV_ID> -e TK_CONTROL_PLANE_URL=<TK_CONTROL_PLANE_URL> -e TK_DASHBOARD_URL=<TK_DASHBOARD_URL> testkube-mcp docker run -i --rm -e TK_ACCESS_TOKEN -e TK_ORG_ID -e TK_ENV_ID -e TK_CONTROL_PLANE_URL -e TK_DASHBOARD_URL docker.io/kubeshop/mcp-server:2.14.2Replace <…> with your own values. 4 more environment variables are in the server README
2Platform CLI: remote server
gemini mcp add -t http testkube-mcp https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about testkube-mcp
How do I install testkube-mcp in Claude Code?
To connect over HTTP, run claude mcp add --transport http testkube-mcp https://api.testkube.io/organizations/{organization_id}/environments/{environment_id}/mcp. Replace the placeholder IDs with your organization and environment values.
What does testkube-mcp do?
It allows AI assistants to manage test workflows, start executions in Kubernetes, and read execution artifacts.
Which transport modes are supported?
You can run it via stdio using Docker image docker.io/kubeshop/mcp-server:2.14.2 or connect over HTTP using the hosted Testkube endpoint.
