Kubeflow MCP Server

![Python 3.10+](https://www.python.org/downloads/) ![Kubeflow SDK](https://pypi.org/project/kubeflow/) ![License](LICENSE) ![MCP](https://modelcontextprotocol.io/) ![Status](#project-status)

AI-powered interface for Kubeflow Training via Model Context Protocol (MCP). Enable your AI assistants to manage distributed training jobs, fine-tune LLMs, and monitor workloads on Kubernetes — all through natural language.

Note: This project is in early development. APIs may change between versions.

!Quick Overview

Overview
Quick Start
Installation
Configuration
Tools
Prompts
CLI
Local Agent
Development
Roadmap
Contributing
Community
License

Overview

The Kubeflow MCP Server bridges AI assistants/agents with Kubeflow's training infrastructure. Instead of writing YAML manifests or learning Kubernetes APIs, simply describe what you want to train and let AI handle the complexity.

Key Benefits

Natural Language Interface: Describe training jobs in plain English — "fine-tune Llama-3 on my dataset with 4 GPUs"
Smart Resource Planning: AI estimates GPU/memory requirements before job submission
Real-time Monitoring: Stream logs, track progress, and debug failures conversationally
Safe by Design: Preview configurations before submission, built-in validation and guardrails
Multi-Client Support: Works with Claude Desktop, Cursor IDE, MCP Inspector, or custom agents

Compatibility

| Component | Version | Notes | |-----------|---------|-------| | Kubeflow SDK | ≥0.4.0 | TrainerClient API for training jobs | | Kubernetes | ≥1.28 | With TrainJob CRD installed | | Python | ≥3.10 | Async support required |

This MCP server wraps the Kubeflow Training SDK TrainerClient API. All training operations (fine-tuning, custom scripts, container jobs) use SDK types like BuiltinTrainer, CustomTrainer, TorchTuneConfig, and LoraConfig.

Quick Start

Installation

pip install kubeflow-mcp

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "kubeflow": {
      "command": "kubeflow-mcp",
      "args": ["serve", "--persona", "ml-engineer"]
    }
  }
}

| Option | Values | Default | |--------|--------|---------| | --persona | readonly, data-scientist, ml-engineer, platform-admin | ml-engineer | | --transport | stdio, http | stdio | | --log-level | DEBUG, INFO, WARNING, ERROR | INFO |

<details> <summary>Config file locations</summary>

| Client | Config Path | |--------|-------------| | Cursor IDE | ~/.cursor/mcp.json | | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |

</details>

<details> <summary>Container deployment</summary>

{
  "mcpServers": {
    "kubeflow": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kube:/home/mcp/.kube:ro",
        "ghcr.io/kubeflow/mcp-server:latest",
        "serve"
      ]
    }
  }
}

Replace podman with docker if needed. </details>

<details> <summary>MCP Inspector (debugging)</summary>

npx @modelcontextprotocol/inspector uv run kubeflow-mcp serve

</details>

Try It

"What training jobs are running in my cluster?"
"Fine-tune google/gemma-2b on squad dataset with 2 GPUs"
"Show me logs for the failed training job"

Tools

| Category | Tools | Description | |----------|-------|-------------| | Planning | get_cluster_resources, estimate_resources | Check capacity, estimate requirements | | Training | fine_tune, run_custom_training, run_container_training | Submit training jobs | | Discovery | list_training_jobs, get_training_job, list_runtimes, get_runtime | Browse jobs and runtimes | | Monitoring | get_training_logs, get_training_events, wait_for_training | Logs, events, status | | Lifecycle | delete_training_job, suspend_training_job, resume_training_job | Manage job lifecycle |

<details> <summary>Example: Fine-tune an LLM</summary>

fine_tune(
    model="google/gemma-2b",
    dataset="squad",
    num_nodes=2,
    gpu_per_node=1,
    confirmed=True
)

</details>

<details> <summary>Example: Resource Estimation</summary>

Ask: "How much GPU memory do I need for Llama-3-70B?"

{
  "model": "meta-llama/Llama-3-70B",
  "parameters": "70B",
  "estimated_memory_gb": 140,
  "recommended_gpus": 4,
  "gpu_type": "A100-80GB"
}

</details>

Prompts

MCP prompts provide structured guidance for common workflows. MCP clients can discover and use these prompts:

| Prompt | Description | |--------|-------------| | fine_tuning_workflow | Step-by-step guide for fine-tuning LLMs with LoRA | | custom_training_workflow | Guide for custom scripts or container training | | troubleshooting_guide | Diagnose and fix common job failures | | resource_planning | Plan resources before training | | monitoring_workflow | Monitor jobs and debug issues |

<details> <summary>Using prompts in MCP clients</summary>

MCP clients that support prompts (like Claude Desktop) can list and invoke these prompts directly. The prompts provide detailed, parameterized guidance that helps ensure successful training operations.

Example with parameters:

fine_tuning_workflow(model="meta-llama/Llama-3.2-3B", dataset="tatsu-lab/alpaca")

</details>

Resources

MCP resources provide read-only reference data that clients can fetch without consuming tool calls:

| Resource URI | Content | |--------------|---------| | trainer://models/supported | Tested model configurations with GPU requirements | | trainer://runtimes/info | Runtime documentation and patches | | trainer://guides/quickstart | Quick start guide for new users | | trainer://guides/troubleshooting | Troubleshooting quick reference |

CLI

# Server
kubeflow-mcp serve                              # Start MCP server
kubeflow-mcp serve --clients trainer            # Specify client
kubeflow-mcp serve --persona ml-engineer        # Set persona
kubeflow-mcp status                             # Show server status

# Agent
kubeflow-mcp agent --backend ollama --model qwen3:8b
kubeflow-mcp agent --backend ollama --mode progressive
kubeflow-mcp agent --backend ollama --thinking  # Enable thinking output

Local Agent

Run a fully local AI agent with Ollama — no cloud APIs required:

pip install kubeflow-mcp[agents]
ollama pull qwen3:8b
kubeflow-mcp agent --backend ollama --model qwen3:8b

!Ollama Agent

<details> <summary>Tool loading modes</summary>

| Mode | Description | |------|-------------| | full | All tools via MCP protocol (default) | | progressive | 3 meta-tools for hierarchical discovery | | semantic | 2 meta-tools with embedding-based search |

kubeflow-mcp agent --backend ollama                    # Full mode (default)
kubeflow-mcp agent --backend ollama --mode progressive # Hierarchical discovery
kubeflow-mcp agent --backend ollama --mode semantic    # requires sentence-transformers

Full mode connects via the standard MCP stdio protocol, identical to Cursor and Claude Desktop. </details>

<details> <summary>Recommended models</summary>

| Model | Context | RAM | Tool Calling | |-------|---------|-----|--------------| | qwen3:8b | 32K | 8GB | ✅ | | qwen2.5:7b | 32K | 7GB | ✅ | | llama3.2:3b | 8K | 3GB | ✅ |

For 8K context models, use --mode progressive or --mode semantic. </details>

<details> <summary>Agent commands</summary>

| Command | Description | |---------|-------------| | /tools | List available tools | | /mode [name] | Switch tool mode | | /file <path> | Read and analyze a file | | /clear | Clear conversation | | exit | Quit | </details>

Development

make dev           # Install dev dependencies
make check         # Lint + type check
make test          # Run tests
make pre-commit    # All checks before commit

See make help for all commands. For detailed setup, see docs/DEVELOPMENT.md.

Roadmap

| Component | Status | Description | |-----------|--------|-------------| | TrainerClient | ✅ Available | 16 training tools | | OptimizerClient | 🔲 Planned | Katib hyperparameter tuning | | ModelRegistryClient | 🔲 Planned | Model versioning |

See ROADMAP.md for details.

For MCP clients, agent frameworks, and production Kubernetes companions (Kyverno, ingress/OIDC, observability) — and what this project supports in-repo vs at deploy time — see Ecosystem and platform integrations in the roadmap.

Contributing

git clone https://github.com/kubeflow/mcp-server.git
cd mcp-server
make dev && make pre-commit

Look for good first issue labels.

| Doc | Description | |-----|-------------| | CONTRIBUTING.md | Guidelines, DCO, code style | | ARCHITECTURE.md | System design | | docs/DEVELOPMENT.md | Local setup, testing | | SECURITY.md | Security policy | | ROADMAP.md | Phases, priorities, ecosystem integrations |

Community

Slack: #kubeflow-ml-experience on CNCF Slack
Meetings: Kubeflow SDK and ML Experience bi-weekly

License

Apache-2.0

Kubeflow MCP Server