Configuration

All configuration is via environment variables. Sensible defaults are built in — you only need to override what you want to change.

---

Installation options

Docker (recommended)

Pull the image and run:

docker run --rm -it \
  -p 8765:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  talkopsai/helm-mcp-server:latest

With custom env vars:

docker run --rm -it \
  -p 9000:9000 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e MCP_PORT=9000 \
  -e MCP_LOG_LEVEL=DEBUG \
  -e MCP_ALLOW_WRITE=false \
  -e HELM_TIMEOUT=600 \
  talkopsai/helm-mcp-server:latest

Read-only mode (no install/upgrade/rollback/uninstall):

docker run --rm -it \
  -p 8765:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e MCP_ALLOW_WRITE=false \
  talkopsai/helm-mcp-server:latest

Build from source (Docker)

cd talkops-mcp/src/helm-mcp-server
docker build -t helm-mcp-server .

docker run --rm -it \
  -p 8765:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  helm-mcp-server

From source (Python)

Using uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/helm-mcp-server

uv venv --python=3.12
source .venv/bin/activate  # On Unix/macOS
uv pip install -e .

Or with pip:

git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/helm-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

---

Environment variables

Pass overrides with -e when running in Docker.

Server

Variable	Default	Description
MCP_SERVER_NAME	helm-mcp-server	Server name identifier
MCP_SERVER_VERSION	0.2.0	Server version string
MCP_TRANSPORT	http	Transport mode: http or stdio
MCP_HOST	0.0.0.0	Host address for HTTP server
MCP_PORT	8765	Port for HTTP server
MCP_PATH	/mcp	MCP endpoint path
MCP_ALLOW_WRITE	true	Enable mutating operations (see below)
MCP_HTTP_TIMEOUT	300	HTTP request timeout (seconds)
MCP_HTTP_KEEPALIVE_TIMEOUT	5	HTTP keepalive timeout (seconds)
MCP_HTTP_CONNECT_TIMEOUT	60	Connection timeout (seconds)
MCP_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
MCP_LOG_FORMAT	json	Log format: json or text

Helm & Kubernetes

Variable	Default	Description
HELM_TIMEOUT	300	Timeout for Helm operations (seconds)
K8S_TIMEOUT	30	Timeout for Kubernetes API calls (seconds)
KUBECONFIG	~/.kube/config	Path to kubeconfig file

---

Write access control

MCP_ALLOW_WRITE controls whether the server accepts mutating operations.

When true (default) — Everything is enabled: install, upgrade, rollback, uninstall, plus all read operations.

When false (read-only) — Only safe operations are allowed:

Allowed	Blocked
Chart search and discovery	helm_install_chart
Value validation	helm_upgrade_release
Manifest rendering	helm_rollback_release
Dependency checking	helm_uninstall_release
Release status and monitoring
Dry-run operations

Dry-runs are always permitted regardless — they don't modify the cluster.

Set MCP_ALLOW_WRITE=false when you want the assistant to explore, validate, and plan — but not actually change anything.

---

MCP client setup

Start the server (Docker or local), then point your MCP client at it:

{
  "mcpServers": {
    "helm-mcp-server": {
      "url": "http://localhost:8765/mcp",
      "description": "Helm MCP Server for managing Kubernetes workloads via Helm"
    }
  }
}

Use the port you configured. Default is 8765.

---

Troubleshooting

Connection timeout — The server takes a few seconds to initialize. Increase your client's connect_timeout to at least 60 seconds and timeout to 300 seconds.

Chart not found — Make sure the chart exists in the repo, run helm repo update, and double-check the repository name (e.g. bitnami, argo).

Helm operations timing out — Set HELM_TIMEOUT=600 (or pass -e HELM_TIMEOUT=600 with Docker).

---

Next steps

• Tools — MCP tools reference
• Resources & Prompts — MCP resources and prompts
• Examples — Usage patterns and workflows