Skip to main content
Glama

Kubectl MCP Tool

INSTALLATION.md8.17 kB
# Installation Guide for kubectl-mcp-tool This document provides detailed instructions for installing the kubectl-mcp-tool, a Kubernetes command-line tool that implements the Model Context Protocol (MCP) to enable AI assistants to interact with Kubernetes clusters. ## Table of Contents - [PyPI Installation](#pypi-installation) - [Prerequisites](#prerequisites) - [Installation Methods](#installation-methods) - [Global Installation](#global-installation) - [Local Development Installation](#local-development-installation) - [Docker Installation](#docker-installation) - [Verifying Installation](#verifying-installation) - [Troubleshooting](#troubleshooting) - [Upgrading](#upgrading) - [Uninstallation](#uninstallation) - [Recommended Configuration](#recommended-configuration) - [Using the Minimal Wrapper (Recommended)](#using-the-minimal-wrapper-recommended) - [Key Environment Variables](#key-environment-variables) - [Testing the Minimal Wrapper](#testing-the-minimal-wrapper) ## PyPI Installation The simplest way to install kubectl-mcp-tool is directly from the Python Package Index (PyPI): ```bash pip install kubectl-mcp-tool ``` For a specific version: ```bash pip install kubectl-mcp-tool==1.1.1 ``` The package is available on PyPI: [https://pypi.org/project/kubectl-mcp-tool/1.1.1/](https://pypi.org/project/kubectl-mcp-tool/1.1.1/) ## Prerequisites Before installing kubectl-mcp-tool, ensure you have the following: - Python 3.9 or higher - pip (Python package manager) - kubectl CLI installed and configured - Access to a Kubernetes cluster - (Optional) Helm v3 for Helm operations To check your Python version: ```bash python --version ``` To check if pip is installed: ```bash pip --version ``` To check if kubectl is installed: ```bash kubectl version --client ``` ## Installation Methods ### Global Installation #### From PyPI (Recommended) Install the latest stable version from PyPI: ```bash pip install kubectl-mcp-tool ``` #### From GitHub Install the development version directly from GitHub: ```bash pip install git+https://github.com/rohitg00/kubectl-mcp-server.git ``` #### Using pipx (Isolated Environment) For a more isolated installation that doesn't affect your system Python: ```bash # Install pipx if you don't have it pip install pipx pipx ensurepath # Install kubectl-mcp-tool pipx install kubectl-mcp-tool ``` ### Local Development Installation If you want to modify the code or contribute to the project: ```bash # Clone the repository git clone https://github.com/rohitg00/kubectl-mcp-server.git cd kubectl-mcp-server # Install dependencies pip install -r requirements.txt # Install in development mode pip install -e . ``` ### Docker Installation For containerized usage: ```bash # Pull the Docker image docker pull rohitg00/kubectl-mcp-tool:latest # Run the container docker run -it --rm \ -v ~/.kube:/root/.kube \ rohitg00/kubectl-mcp-tool:latest ``` ## Recommended Configuration ### Using the Minimal Wrapper (Recommended) For best compatibility with AI assistants, we strongly recommend using the minimal wrapper provided in the package. This approach resolves many common issues including JSON RPC errors and logging problems: ```json { "mcpServers": { "kubernetes": { "command": "python", "args": ["-m", "kubectl_mcp_tool.minimal_wrapper"], "env": { "KUBECONFIG": "/path/to/your/.kube/config", "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin", "MCP_LOG_FILE": "/path/to/logs/debug.log", "MCP_DEBUG": "1" } } } } ``` ### Key Environment Variables - `MCP_LOG_FILE`: Path to log file (recommended to avoid stdout pollution) - `MCP_DEBUG`: Set to "1" for verbose logging - `MCP_TEST_MOCK_MODE`: Set to "1" to use mock data instead of real cluster - `KUBECONFIG`: Path to your Kubernetes config file - `KUBECTL_MCP_LOG_LEVEL`: Set to "DEBUG", "INFO", "WARNING", or "ERROR" ### Testing the Minimal Wrapper You can verify that the minimal wrapper is working correctly: ```bash # Test directly python -m kubectl_mcp_tool.minimal_wrapper # Use the ping utility to test connectivity python -m kubectl_mcp_tool.simple_ping ``` ## Verifying Installation After installation, verify that the tool is working correctly: ```bash # Check version kubectl-mcp --version # Check CLI mode kubectl-mcp --help # Test connection to Kubernetes kubectl-mcp get pods ``` ## Troubleshooting ### Common Issues 1. **Command not found**: - Ensure the installation directory is in your PATH - For pipx installations, run `pipx ensurepath` and restart your terminal 2. **Permission errors during installation**: - Use `pip install --user kubectl-mcp-tool` to install for the current user only - On Linux/macOS, you might need to use `sudo pip install kubectl-mcp-tool` 3. **Dependency conflicts**: - Create a virtual environment: `python -m venv venv && source venv/bin/activate` - Then install within the virtual environment 4. **Kubernetes connection issues**: - Ensure your kubeconfig is correctly set up: `kubectl config view` - Check that your cluster is accessible: `kubectl cluster-info` 5. **ImportError: cannot import name 'Parameter' from 'mcp.types'**: - This is due to an MCP SDK version mismatch. Run the following commands to fix: ```bash # Uninstall conflicting packages pip uninstall -y kubectl-mcp-tool fastmcp mcp mcp-python # Install the correct version pip install mcp>=1.5.0 # Reinstall kubectl-mcp-tool pip install kubectl-mcp-tool ``` 6. **AttributeError: module 'kubectl_mcp_tool.cli' has no attribute 'main'**: - This is due to a CLI module path issue. Update your installation: ```bash pip uninstall -y kubectl-mcp-tool git clone https://github.com/rohitg00/kubectl-mcp-server.git cd kubectl-mcp-server pip install -e . ``` - Or use our automatic install script: ```bash bash install.sh ``` 7. **MCP Server compatibility issues**: - Make sure you're using the correct MCP configuration for your AI assistant - For Cursor AI, use this configuration in `~/.cursor/mcp.json`: ```json { "mcpServers": { "kubernetes": { "command": "python", "args": ["-m", "kubectl_mcp_tool.minimal_wrapper"], "env": { "KUBECONFIG": "/path/to/your/.kube/config", "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin" } } } } ``` - Replace `/path/to/your/.kube/config` with your actual kubeconfig path (usually `~/.kube/config`) - The `minimal_wrapper` module provides the most stable implementation for AI assistants 8. **Server implementation issues**: - This tool uses FastMCP from MCP SDK 1.5.0+ with a minimal wrapper approach - Key points about the implementation: - We use the simple `@server.tool(name)` decorator format without complex parameters - The minimal wrapper has better compatibility across MCP SDK versions - For debugging issues, run: `python -m kubectl_mcp_tool.minimal_wrapper` 9. **Client closed or connection errors**: - If you see "client closed" errors in your AI assistant, check: - Your kubeconfig path is correct in the configuration - kubectl is installed and in your PATH - You have proper permissions to access your Kubernetes cluster - Run the installation script: `bash install.sh` which handles these issues automatically ### Getting Help If you encounter issues not covered here: 1. Check the [GitHub Issues](https://github.com/rohitg00/kubectl-mcp-server/issues) for similar problems 2. Join our [Discord community](https://discord.gg/kubectl-mcp) for real-time support 3. Open a new issue on GitHub with details about your problem ## Upgrading To upgrade to the latest version: ```bash pip install --upgrade kubectl-mcp-tool ``` To upgrade to a specific version: ```bash pip install --upgrade kubectl-mcp-tool==1.0.0 ``` ## Uninstallation To uninstall kubectl-mcp-tool: ```bash pip uninstall kubectl-mcp-tool ``` If installed with pipx: ```bash pipx uninstall kubectl-mcp-tool ```

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rohitg00/kubectl-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server