mcp-cyclops

Purpose

Cyclops MCP (Model Context Protocol) server allows AI agents to manage Kubernetes applications. It provides tools that let agents safely create and update existing applications.

Main Capabilities

• Inspect all existing templates and their schemas to create accurate, production-ready applications.
• Agents create high-level resources (Cyclops Modules) instead of manipulating Kubernetes resources (Deployment, Service, Ingress) line by line, greatly reducing the possibility of misconfiguration.
• Helps move quickly while ensuring that no uncaught misconfiguration reaches production.
• Through Cyclops and MCP, Kubernetes complexity is abstracted away from developers and AI agents.

Usage

Install via Cyclops UI (recommended)

⚠️ Installing Cyclops MCP via the UI requires Cyclops version v0.20.1 or higher.

1. In the sidebar, go to "Addon" > "MCP server".
2. Click "Install Cyclops MCP server", and after a few seconds the MCP server will be running.
3. Expose the MCP server outside the cluster and connect an AI agent. For local exposure, you can use port forwarding:

kubectl port-forward -n cyclops svc/cyclops-mcp 8000:8000

The server will be available at localhost:8000.

1. Provide the Cyclops MCP server in the AI agent configuration. For example, add it to Cursor:

{
  "mcpServers": {
    "cyclops-kubernetes": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Install via binary

1. Ensure Cyclops is already installed in the Kubernetes cluster. Installation documentation:https://cyclops-ui.com/docs/installation/install/manifest
2. Download the MCP server binary.
3. Add the server configuration. ⚠️ By default, Cyclops MCP uses the .kube/config file to connect to the cluster. The Cyclops MCP server can be configured via environment variables, for example to specify the kubeconfig file it should use when managing Cyclops applications.

Install via kubectl (SSE transport)

Instead of having each developer install the mcp-cyclops binary, you can install the Cyclops MCP server into the Kubernetes cluster using SSE as the transport type, allowing all developers to connect to the same server.

Before installation, ensure that Cyclops and all its CRDs are installed:

Check whether the Cyclops Pod is running:

kubectl get pods -n cyclops

It should output something like:

NAME                            READY   STATUS    RESTARTS   AGE
cyclops-ctrl-676b5d9789-ntcls   1/1     Running   0          94s
cyclops-ui-7798655f97-xdg29     1/1     Running   0          94s

Check whether the CRDs are installed:

kubectl get crds | grep cyclops-ui

It should output something like:

modules.cyclops-ui.com          2025-04-26T15:28:18Z
templateauthrules.cyclops-ui.com 2025-04-26T15:28:18Z
templatestores.cyclops-ui.com    2025-04-26T15:28:18Z

Install the Cyclops MCP server:

kubectl apply -f https://raw.githubusercontent.com/cyclops-ui/mcp-cyclops/refs/heads/main/install/mcp-server.yaml

Expose the cyclops-mcp service. For testing, you can use port forwarding:

kubectl port-forward svc/cyclops-mcp -n cyclops 8000:8000

Add the Cyclops MCP server host, or use the localhost address from port forwarding for testing:

{
  "mcpServers": {
    "mcp-cyclops": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Use Cases

• Teams that want to let AI agents safely create and update Kubernetes applications.
• Scenarios where you want to reduce Kubernetes misconfiguration through high-level abstractions (Cyclops Modules).
• Teams that need multiple developers to share the same MCP server (SSE transport method).

Limitations

• Installing via the UI requires Cyclops v0.20.1 or higher.
• By default, it uses the .kube/config file to connect to the cluster.
• Details such as the list of other environment variables and binary download commands are not yet fully provided in the supplied materials.