# MCP-K8sWizard Installation Manual
This manual provides step-by-step instructions for installing and configuring MCP-K8sWizard to work with Cursor AI.
## 📋 Prerequisites
Before installing MCP-K8sWizard, ensure you have the following:
### Required Software
- **Go 1.25.1 or later** - [Download Go](https://golang.org/dl/)
- **Kubernetes cluster access** - Local (minikube, kind, k3s) or cloud (EKS, AKS, GKE)
- **Cursor AI** - [Download Cursor](https://cursor.sh/)
- **kubectl** - [Install kubectl](https://kubernetes.io/docs/tasks/tools/)
### System Requirements
- **Operating System**: macOS or Linux
- **Memory**: Minimum 4GB RAM (8GB recommended)
- **Storage**: 100MB free space
- **Network**: Internet access for downloading dependencies
## 🚀 Installation Methods
### Method 1: Quick Install (Recommended)
1. **Clone the repository**
```bash
git clone https://github.com/your-org/mcp-k8swizard.git
cd mcp-k8swizard
```
2. **Install using Makefile**
```bash
# Install to system PATH (requires sudo)
make install
# OR install to user PATH (no sudo required)
make install-user
# OR install using go install (no sudo required)
make install-go
```
3. **Verify installation**
```bash
mcp-k8swizard --version
```
### Method 2: Build Only (No Installation)
1. **Clone the repository**
```bash
git clone https://github.com/your-org/mcp-k8swizard.git
cd mcp-k8swizard
```
2. **Build the binary**
```bash
make build
```
3. **Run from current directory**
```bash
./mcp-k8swizard --version
```
### Method 3: Development Setup
1. **Clone the repository**
```bash
git clone https://github.com/your-org/mcp-k8swizard.git
cd mcp-k8swizard
```
2. **Build the project**
```bash
make build
```
### Available Makefile Targets
The Makefile provides several useful targets for different scenarios:
```bash
# Show all available targets
make help
# Build targets
make build # Build the binary
make build-linux # Build for Linux
make build-all # Build for all platforms
# Install targets
make install # Install to system PATH (requires sudo)
make install-user # Install to user PATH (no sudo)
make install-go # Install using go install
# Development targets
make deps # Download dependencies
make fmt # Format code
make lint # Run linter
make vet # Run go vet
# Clean targets
make clean # Clean build artifacts
# Quick start
make quickstart # Complete quick start setup
```
## ⚙️ Configuration
### 1. Kubernetes Configuration
Ensure your Kubernetes cluster is accessible:
```bash
# Check cluster connection
kubectl cluster-info
# Verify contexts
kubectl config get-contexts
# Set default context (optional)
kubectl config use-context your-context-name
```
### 2. Cursor AI Configuration
Create or edit the MCP configuration file:
**Location**: `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"k8s-wizard": {
"command": "/path/to/mcp-k8swizard",
"args": ["--verbose"],
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig",
"K8S_CONTEXT": "your-context-name"
}
}
}
}
```
**Replace the following:**
- `/path/to/mcp-k8swizard` - Full path to your MCP-K8sWizard binary
- `/path/to/your/kubeconfig` - Path to your kubeconfig file (usually `~/.kube/config`)
- `your-context-name` - Your Kubernetes context name (optional)
### 3. Environment Variables (Optional)
You can set these environment variables for additional configuration:
```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.profile
export KUBECONFIG="/path/to/your/kubeconfig"
export K8S_CONTEXT="your-context-name"
export LOG_LEVEL="INFO"
export LOG_FILE="/tmp/mcp-k8swizard.log"
```
## 🔧 Cursor AI Setup
### 1. Restart Cursor AI
After configuring the MCP settings, restart Cursor AI to load the new configuration.
### 2. Verify MCP Connection
In Cursor AI, you should see MCP-K8sWizard available in your tools. Test the connection:
```
"Show me my Kubernetes clusters"
```
### 3. Test Basic Operations
Try these commands to verify everything is working:
```
"List all pods in the default namespace"
"Get cluster information"
"Show me all available contexts"
```
## 🐛 Troubleshooting
### Common Issues
#### 1. MCP-K8sWizard not appearing in Cursor AI
**Symptoms**: MCP-K8sWizard doesn't show up in available tools
**Solutions**:
- Verify `~/.cursor/mcp.json` exists and is valid JSON
- Check that the path to `mcp-k8swizard` is correct
- Restart Cursor AI completely
- Check Cursor AI logs for MCP errors
#### 2. Kubernetes connection errors
**Symptoms**: "Failed to connect to Kubernetes cluster" errors
**Solutions**:
```bash
# Test kubectl connection
kubectl cluster-info
# Check kubeconfig
kubectl config view
# Verify context
kubectl config current-context
```
#### 3. Permission denied errors
**Symptoms**: "Permission denied" when running commands
**Solutions**:
```bash
# Make binary executable
chmod +x mcp-k8swizard
# Check file permissions
ls -la mcp-k8swizard
```
#### 4. Go build errors
**Symptoms**: Build fails with Go module errors
**Solutions**:
```bash
# Clean and rebuild using Makefile
make clean
make deps
make build
# Or manually clean module cache
go clean -modcache
go mod download
go version
```
#### 5. Makefile not found
**Symptoms**: "make: command not found" or "Makefile not found"
**Solutions**:
```bash
# Install make (if not available)
# On macOS with Homebrew
brew install make
# On Ubuntu/Debian
sudo apt-get install make
# On CentOS/RHEL
sudo yum install make
# Verify make is available
make --version
```
#### 6. Permission denied during installation
**Symptoms**: Permission errors when running `make install`
**Solutions**:
```bash
# Use user installation instead
make install-user
# Or use go install
make install-go
# Or build only and run from current directory
make build
./mcp-k8swizard --version
```
### Debug Mode
Enable debug logging for troubleshooting:
```json
{
"mcpServers": {
"k8s-wizard": {
"command": "/path/to/mcp-k8swizard",
"args": ["--verbose", "--log-level=DEBUG"]
}
}
}
```
### Log Files
Check log files for detailed error information:
```bash
# Default log location
tail -f /tmp/mcp-k8swizard.log
# Or check stdout if no log file specified
```
## 🔄 Updates
### Updating MCP-K8sWizard
1. **Pull latest changes**
```bash
git pull origin main
```
2. **Rebuild the binary**
```bash
go build -o mcp-k8swizard .
```
3. **Restart Cursor AI**
### Updating Cursor AI
When updating Cursor AI, your MCP configuration should persist. If not, re-add the configuration to `~/.cursor/mcp.json`.
## 🗑️ Uninstallation
### Remove MCP-K8sWizard
1. **Stop Cursor AI**
2. **Remove MCP configuration**
```bash
# Edit ~/.cursor/mcp.json and remove the k8s-wizard entry
```
3. **Remove binary using Makefile**
```bash
# If installed using make install
cd /path/to/mcp-k8swizard
make clean
sudo rm /usr/local/bin/mcp-k8swizard
# If installed using make install-user
rm ~/bin/mcp-k8swizard
# If installed using make install-go
go clean -i
```
4. **Remove project directory (optional)**
```bash
rm -rf /path/to/mcp-k8swizard
```
## 📞 Support
If you encounter issues not covered in this manual:
1. **Check the logs** for detailed error messages
2. **Search existing issues** on [GitHub Issues](https://github.com/your-org/mcp-k8swizard/issues)
3. **Create a new issue** with:
- Your operating system
- Go version (`go version`)
- Kubernetes version (`kubectl version`)
- Cursor AI version
- Error logs
- Steps to reproduce
## 📚 Additional Resources
- [Main README](../README.md) - Overview and features
- [Configuration Guide](configuration.md) - Advanced configuration options
- [Troubleshooting Guide](troubleshooting.md) - Detailed troubleshooting steps
- [API Reference](api-reference.md) - Complete API documentation
---
**Need help?** Join our [Discord community](https://discord.gg/your-discord) or open an issue on GitHub!