# Configuration Guide
This guide covers configuration options for MCP-K8sWizard, including environment variables, command-line options, and Cursor AI integration settings.
## Table of Contents
- [Environment Variables](#environment-variables)
- [Command Line Options](#command-line-options)
- [Cursor AI Integration](#cursor-ai-integration)
- [Kubernetes Configuration](#kubernetes-configuration)
- [Logging Configuration](#logging-configuration)
- [Best Practices](#best-practices)
## Environment Variables
MCP-K8sWizard supports the following environment variables:
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` | No |
| `K8S_CONTEXT` | Default Kubernetes context | Current context | No |
| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARN, ERROR) | `INFO` | No |
### Setting Environment Variables
```bash
# Set kubeconfig path
export KUBECONFIG=~/.kube/config
# Set Kubernetes context
export K8S_CONTEXT=my-context
# Set log level
export LOG_LEVEL=DEBUG
```
## Command Line Options
### Basic Options
```bash
./mcp-k8swizard [OPTIONS]
Options:
-log-level string
Set log level (DEBUG, INFO, WARN, ERROR)
-verbose
Enable verbose logging (equivalent to DEBUG level)
-version
Show version information
-help
Show help information
```
### Usage Examples
```bash
# Run with debug logging
./mcp-k8swizard --verbose
# Run with specific log level
./mcp-k8swizard --log-level=DEBUG
# Show version
./mcp-k8swizard --version
# Show help
./mcp-k8swizard --help
```
## Cursor AI Integration
### Basic Configuration
Add to your `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"k8s-wizard": {
"command": "/path/to/mcp-k8swizard",
"args": ["--verbose"],
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig",
"LOG_LEVEL": "INFO"
}
}
}
}
```
### Advanced Configuration
```json
{
"mcpServers": {
"k8s-wizard": {
"command": "/path/to/mcp-k8swizard",
"args": [
"--log-level=DEBUG"
],
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig",
"K8S_CONTEXT": "production",
"LOG_LEVEL": "DEBUG"
}
}
}
}
```
### Multiple Server Instances
```json
{
"mcpServers": {
"k8s-wizard-dev": {
"command": "/path/to/mcp-k8swizard",
"args": ["--log-level=DEBUG"],
"env": {
"KUBECONFIG": "/path/to/dev/kubeconfig",
"K8S_CONTEXT": "development"
}
},
"k8s-wizard-prod": {
"command": "/path/to/mcp-k8swizard",
"args": ["--log-level=WARN"],
"env": {
"KUBECONFIG": "/path/to/prod/kubeconfig",
"K8S_CONTEXT": "production"
}
}
}
}
```
## Kubernetes Configuration
### Kubeconfig Setup
MCP-K8sWizard automatically detects and uses your existing kubeconfig:
1. **Default location**: `~/.kube/config`
2. **Custom location**: Set `KUBECONFIG` environment variable
3. **Context selection**: Set `K8S_CONTEXT` environment variable
### Example Kubeconfig
```yaml
apiVersion: v1
kind: Config
clusters:
- cluster:
server: https://kubernetes.default.svc
certificate-authority-data: LS0tLS1CRUdJTi...
name: local-cluster
contexts:
- context:
cluster: local-cluster
user: local-user
name: local-context
current-context: local-context
users:
- name: local-user
user:
token: eyJhbGciOiJSUzI1NiIs...
```
### RBAC Configuration
Create a service account with appropriate permissions:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: mcp-k8swizard
namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: mcp-k8swizard
rules:
- apiGroups: [""]
resources: ["pods", "services", "endpoints", "persistentvolumeclaims", "events", "configmaps", "secrets"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["apps"]
resources: ["deployments", "daemonsets", "replicasets", "statefulsets"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["extensions"]
resources: ["deployments", "replicasets"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["networking.k8s.io"]
resources: ["ingresses", "networkpolicies"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: mcp-k8swizard
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: mcp-k8swizard
subjects:
- kind: ServiceAccount
name: mcp-k8swizard
namespace: default
```
## Logging Configuration
### Log Levels
- **DEBUG**: Detailed information for debugging
- **INFO**: General information about program execution
- **WARN**: Warning messages for potential issues
- **ERROR**: Error messages for failures
### Setting Log Level
```bash
# Via environment variable
export LOG_LEVEL=DEBUG
# Via command line
./mcp-k8swizard --log-level=DEBUG
# Via verbose flag
./mcp-k8swizard --verbose
```
### Log Output
MCP-K8sWizard logs to:
- **Default**: `~/mcp-k8swizard-logs` (JSON format)
- **Fallback**: `stderr` if log file cannot be created
### Log Format
Logs are in JSON format for easy parsing:
```json
{
"timestamp": "2024-01-15T10:30:00Z",
"level": "INFO",
"message": "Tool executed successfully",
"tool": "k8s_get_pods",
"namespace": "default",
"duration_ms": 150
}
```
## Configuration Validation
### Check Configuration
```bash
# Check version and help
./mcp-k8swizard --version
./mcp-k8swizard --help
# Test Kubernetes connection
kubectl cluster-info
# Check MCP server status (stdio-based)
ps aux | grep mcp-k8swizard
```
### Common Configuration Issues
1. **Invalid kubeconfig path**
```bash
Error: stat /path/to/kubeconfig: no such file or directory
Solution: Verify the kubeconfig path and file permissions
```
2. **Invalid context**
```bash
Error: context "invalid-context" does not exist
Solution: Check available contexts with `kubectl config get-contexts`
```
3. **Permission denied**
```bash
Error: pods is forbidden: User cannot list resource "pods"
Solution: Update RBAC permissions for the service account
```
## Best Practices
1. **Use environment variables** for configuration
2. **Set appropriate log levels** (DEBUG for development, WARN for production)
3. **Use separate contexts** for different environments
4. **Regularly review RBAC permissions**
5. **Monitor log files** for errors and performance issues
6. **Test configuration** in development before production
7. **Keep kubeconfig files secure** and properly configured
## Environment-Specific Configurations
### Development Environment
```bash
# Development configuration
export LOG_LEVEL=DEBUG
export K8S_CONTEXT=dev-context
```
### Production Environment
```bash
# Production configuration
export LOG_LEVEL=WARN
export K8S_CONTEXT=prod-context
```
## Troubleshooting
### Configuration Issues
1. **Check environment variables:**
```bash
echo "KUBECONFIG: $KUBECONFIG"
echo "K8S_CONTEXT: $K8S_CONTEXT"
echo "LOG_LEVEL: $LOG_LEVEL"
```
2. **Test Kubernetes connectivity:**
```bash
kubectl cluster-info
kubectl get nodes
```
3. **Check MCP server status:**
```bash
ps aux | grep mcp-k8swizard
```
### Getting Help
- **Documentation**: [Installation Manual](installation.md)
- **Troubleshooting**: [Troubleshooting Guide](troubleshooting.md)
- **API Reference**: [API Reference](api-reference.md)
## Next Steps
- [Installation Manual](installation.md) - Complete setup guide
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
- [API Reference](api-reference.md) - Complete tool documentation