Configuration

Complete configuration guide for the Helm MCP Server including environment variables, Docker setup, MCP client configuration, and access control.

---

📦 Installation Options

Option 1: Docker Hub (Recommended)

The easiest way to get started is using the pre-built Docker image.

# Pull the image
docker pull sandeep2014/talkops-mcp:helm-mcp-server-latest

# Run with default configuration (port 8765)
docker run --rm -it \
  -p 8765:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  sandeep2014/talkops-mcp:helm-mcp-server-latest

# Run with custom environment variables
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 \
  sandeep2014/talkops-mcp:helm-mcp-server-latest

# Run in read-only mode
docker run --rm -it \
  -p 8765:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e MCP_ALLOW_WRITE=false \
  sandeep2014/talkops-mcp:helm-mcp-server-latest

# Map to different host port
docker run --rm -it \
  -p 8080:8765 \
  -v ~/.kube/config:/app/.kube/config:ro \
  sandeep2014/talkops-mcp:helm-mcp-server-latest

Option 2: Build from Source (Docker)

# Navigate to the helm-mcp-server directory
cd talkops-mcp/src/helm-mcp-server

# Build the image
docker build -t helm-mcp-server .

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

Option 3: Using uv

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone git@github.com:talkops-ai/talkops-mcp.git
cd talkops-mcp/src/helm-mcp-server

# Create virtual environment and install
uv venv --python=3.12
source .venv/bin/activate  # On Unix/macOS
# .venv\Scripts\activate   # On Windows

uv pip install -e .

Option 4: Using pip

git clone git@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

note

When running in Docker, environment variables set via -e flags will override the defaults in the Docker image.

Server Configuration

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 (HTTP/SSE) or stdio
MCP_HOST	0.0.0.0	Host address for HTTP/SSE server
MCP_PORT	8765	Port for HTTP/SSE server
MCP_PATH	/sse	SSE endpoint path
MCP_ALLOW_WRITE	true	Enable write operations (see below)
MCP_HTTP_TIMEOUT	300	HTTP request timeout in seconds
MCP_HTTP_KEEPALIVE_TIMEOUT	5	HTTP keepalive timeout in seconds
MCP_HTTP_CONNECT_TIMEOUT	60	HTTP connection timeout in seconds
MCP_LOG_LEVEL	INFO	Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
MCP_LOG_FORMAT	json	Log format: json or text

Helm Configuration

Variable	Default	Description
HELM_TIMEOUT	300	Timeout in seconds for Helm operations

Kubernetes Configuration

Variable	Default	Description
K8S_TIMEOUT	30	Timeout in seconds for Kubernetes API operations
KUBECONFIG	~/.kube/config	Path to kubeconfig file

---

🔐 Write Access Control

The MCP_ALLOW_WRITE environment variable controls whether mutating operations are allowed. This is a critical security feature.

When MCP_ALLOW_WRITE=true (Default)

All operations are enabled:

Operation	Tool	Status
Install	helm_install_chart	✅ Enabled
Upgrade	helm_upgrade_release	✅ Enabled
Rollback	helm_rollback_release	✅ Enabled
Uninstall	helm_uninstall_release	✅ Enabled
Dry-run	All dry-run operations	✅ Enabled

When MCP_ALLOW_WRITE=false (Read-Only Mode)

Only read-only operations are allowed:

Operation	Status
Discovery (search charts, get info)	✅ Allowed
Validation (validate values, render manifests)	✅ Allowed
Monitoring (get status, list releases)	✅ Allowed
Dry-run operations	✅ Allowed
Install	❌ Blocked
Upgrade	❌ Blocked
Rollback	❌ Blocked
Uninstall	❌ Blocked

Use Case

Set MCP_ALLOW_WRITE=false when you want to use the server for discovery, validation, and monitoring only—preventing any accidental deployments or modifications.

note

Dry-run operations (dry_run=True) are always allowed, even when MCP_ALLOW_WRITE=false, as they don't modify the cluster.

---

🔌 MCP Client Configuration

Step 1: Start the Server

Using Docker:

docker run --rm -it \
  -p 9000:9000 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e MCP_PORT=9000 \
  -e MCP_ALLOW_WRITE=true \
  -e MCP_LOG_LEVEL=INFO \
  sandeep2014/talkops-mcp:helm-mcp-server-latest

Using Local Installation:

cd /path/to/talkops-mcp/src/helm-mcp-server
source .venv/bin/activate
helm-mcp-server

Step 2: Configure the Client

Configure your MCP client to connect using SSE (Server-Sent Events) transport:

{
  "mcpServers": {
    "helm-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:9000/sse",
      "description": "Helm MCP Server for managing Kubernetes workloads via Helm",
      "disabled": false,
      "autoApprove": []
    }
  }
}

note

Replace 9000 with the port you configured when starting the server. The default port is 8765 if not specified.

---

🔧 Troubleshooting

Connection Timeout Errors

If you encounter httpx.ConnectTimeout errors, increase the client timeout values:

{
    "url": "http://localhost:8765/sse",
    "transport": "sse",
    "timeout": 300.0,           # Increase to 300 seconds
    "connect_timeout": 60.0     # Increase to 60 seconds
}

Why this happens:

• Server may take time to initialize
• Network latency between client and server
• Default client timeout may be insufficient

Chart Not Found Errors

1. Ensure the chart exists in the specified repository
2. Run helm repo update to refresh repository indexes
3. Check the repository name is correct (e.g., bitnami, argo)

Helm Command Timeouts

Increase the timeout via environment variable:

export HELM_TIMEOUT=600  # 10 minutes

---

Next Steps

• 🛠️ Tools - Available MCP tools reference
• 📁 Resources & Prompts - MCP resources and prompts
• 📖 Examples - Usage patterns and workflows