Flux MCP Server
Flux CD MCP server from the Flux Operator project: an agent debugs failed rollouts in Kubernetes, compares clusters and applies manifests on request
- 783 ★ on the repository
- Last commit
- AGPL-3.0
Broad access
Why this level
- The tools apply manifests, patch and delete cluster resources when the server runs without read-only mode
- The server acts with the rights from your kubeconfig and reads workload logs and metrics
- Without masking, Kubernetes Secret values reach the assistant and its model
Install
- Works in
Manual install
brew install controlplaneio-fluxcd/tap/flux-operator-mcpOther install options are in the guide on the project site. You need a working kubeconfig for a cluster with Flux.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The tools apply manifests, patch and delete cluster resources when the server runs without read-only mode
- The server acts with the rights from your kubeconfig and reads workload logs and metrics
- Without masking, Kubernetes Secret values reach the assistant and its model
This is third-party code. Review the repository files before installing.
What it does
Flux MCP Server is an MCP server that connects an AI agent to a Kubernetes cluster running Flux CD and Flux Operator. Instead of hand-typed kubectl and flux commands, the agent calls the server's tools: it checks the Flux version and installation health, reads resources together with events and readiness conditions, pulls pod logs and metrics, and walks the owner chain from a pod up to a Kustomization, HelmRelease or Git source. That is how it finds the link of the GitOps pipeline where a rollout stalled. The server can also change the cluster: trigger a fresh reconcile of a resource, suspend and resume it, apply a manifest with server-side apply, patch and delete resources, and install a Flux instance from a manifest URL. Before applying, the agent can check a change with `diff_kubernetes_manifest`, which shows the difference and writes nothing. For several clusters, `get_kubeconfig_contexts` and `set_kubeconfig_context` switch the session context without touching the kubeconfig file. `search_flux_docs` and `read_flux_doc` search the Flux documentation. The server starts with `flux-operator-mcp serve`. It runs over stdio by default, and with `--transport http` it answers over Streamable HTTP at the /mcp path. On connection it hands the agent built-in instructions. The authors suggest copying the step-by-step debugging rules from docs/mcp/instructions.md into your assistant's rules file.
Who it is for. For platform engineers and DevOps teams that run clusters on Flux CD and want an agent in Claude, Cursor or GitHub Copilot to debug failed rollouts, compare environments and handle routine Flux operations.
Good fit when
- A HelmRelease or Kustomization will not become ready and you need to trace the path from the pod and its events to the Git source
- Staging and production have drifted and you need to compare Flux and resource configuration across two clusters
- You need a Flux dependency diagram built from the real cluster state
- You must suspend reconciliation of a failing resource right now, then resume it and trigger it again after a fix
- Before applying a manifest you want to see how it differs from what runs in the cluster
Not a fit when
- The cluster does not use Flux: the server is built around Flux resources and docs; for general Kubernetes work the catalog has Kubernetes MCP Server
- The agent has no access to the kubeconfig of the target cluster: the server works with the credentials it finds in that file
- You need one shared server address for a whole team without a local kubeconfig file: the local stdio launch is meant for one machine
- Only a person should change the cluster: then start the server strictly with `--read-only` and give the agent no write rights
Example request
The podinfo HelmRelease in the apps namespace will not become ready. Find the cause from events and logs, show the chain from the pod to the source and change nothingMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
KUBECONFIGrequired- Absolute path to the kubeconfig file of the cluster the server works with.
Limitations
The server is part of the Flux Operator project and ships under the AGPL-3.0 license.
Write tools are on by default. The `--read-only` flag disables reconcile, suspend, resume, apply and delete. The manifest diff tool stays available, but Kubernetes authorizes its server-side dry run like a real apply, so it needs `get` and `patch` on the manifest kinds. A view-only account gets per-object access errors.
The server masks Kubernetes Secret values by default. The author warns that with `--mask-secrets=false` secrets go to the assistant and possibly into its model's training data, so it should be done only in a controlled environment with a self-hosted model.
The SSE transport was removed and only Streamable HTTP is supported, while the `yaml_path` input of the diff tool exists only for a local stdio launch. The kubeconfig path comes from the KUBECONFIG variable, and the `--kube-as` flag limits the server to the rights of a chosen service account.
How to disable. Remove the flux-operator-mcp entry from your assistant's MCP settings and restart it. If you installed through Homebrew, `brew uninstall flux-operator-mcp` removes the program. If the server was deployed in a cluster through a ResourceSet, delete that resource.
FAQ
How do I run Flux MCP Server in read-only mode?
Add the `--read-only` flag to args. Tools that change cluster state are then disabled: reconcile, suspend, resume, apply and delete. Reading resources, logs, events and metrics stays available.
How do I connect Flux MCP Server to Claude, Cursor or GitHub Copilot?
Add an entry to the assistant's MCP settings with the command flux-operator-mcp and the argument serve, and set KUBECONFIG to the absolute path of your kubeconfig file. Restart the assistant and check the connection by asking for the available kubeconfig contexts. Per-assistant details are in the project's documentation.
Do I need Flux Operator in the cluster?
The server is described as a bridge between an assistant and clusters running Flux Operator. If the operator is missing, `install_flux_instance` installs it together with a Flux instance from a manifest URL; the URL can be an HTTPS or OCI link.
How do I compare two Flux clusters through an agent?
The agent switches context with `set_kubeconfig_context`, reads the resources in each cluster and sets them side by side. There are no simultaneously connected clusters: a session holds one context, and it changes without editing the kubeconfig.
Can I limit the server's rights with a dedicated account?
Yes, with `--kube-as` set to a value like system:serviceaccount:my-namespace:my-service-account. The server then holds only that service account's rights, and the user in the kubeconfig needs the impersonation permission.
How do I run the server over the network instead of stdio?
With `flux-operator-mcp serve --transport http --port 8080`. A client connects at http://localhost:8080/mcp with type http. The server keeps no session state, so it can scale behind a load balancer without sticky clients.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server for Kubernetes: the agent reads cluster state, diagnoses pod failures and runs operations through kubectl
A Go MCP server for Kubernetes and OpenShift: resources, pods, logs, Helm and Tekton straight through the cluster API
Kubernetes MCP
MCP Server Kubernetes
MCP server for managing a Kubernetes cluster through kubectl and Helm, with a non-destructive mode
A self-hosted gateway that merges several MCP servers into one endpoint with auth and tool selection
Official Cloudflare MCP server: the agent drives the whole Cloudflare API by searching the spec and running code
SSH MCP Server (classfang): remote commands over SSH
SSH MCP Server (classfang)
An SSH MCP server: the agent runs commands, reads and writes files over SFTP, transfers files and starts long jobs while credentials stay with you
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Flux MCP Server (this entry) | yes | not required | 783 | |
| Kubernetes MCP Server | no | not required | 2,200 | general MCP server for Kubernetes and OpenShift, not tied to Flux |
| Argo CD MCP Server | no | API key | 601 | server for Argo CD, a different GitOps tool |
README in short
The repository holds the server's source code, a Dockerfile, a quickstart and a documentation folder with five pages: installation, transport and security configuration, prompting advice, a tools reference and ready instructions for the assistant. The quickstart comes down to installing through Homebrew, adding an entry to the MCP settings and checking with two questions: which contexts the kubeconfig has and which Flux version runs in the current cluster.