{"id":"e023c6b9-9cbb-442f-9348-b57de193475b","slug":"pmithil7-kube-mcp-server","kind":"mcp","name":"kube-mcp-server","summary":"Kubernetes FastAPI MCP server that uses kubectl to manage K8s eco-system using natural language","owner":"pmithil7","repoUrl":"https://github.com/pmithil7/kube-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-09-17T20:48:04.000Z","addedAt":"2026-10-21T15:55:08.349Z","logoUrl":"https://avatars.githubusercontent.com/u/47230375?u=e7a4e891609a0e259ef3cc7edd2dcaa48f97d184&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T15:28:07.451Z","sample":false,"url":"https://conduits.dev/tools/pmithil7-kube-mcp-server","language":"Python","transports":["stdio"],"install":{"pypi":"kube-mcp-server"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# kube-mcp-server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)\n[![MCP](https://img.shields.io/badge/MCP-1.12+-purple.svg)](https://modelcontextprotocol.io/)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/r/pmithil7/kube-mcp-server)\n\nA **production-ready FastAPI-based Model Context Protocol (MCP) server** that enables AI assistants like Claude, Cursor, and GitHub Copilot to manage Kubernetes clusters through natural language. Features multi-context support, security controls, and comprehensive cluster diagnostics.\n\n## 🚀 Features\n\n- **🔐 Security-First Design**: Built-in destructive command blocklist prevents dangerous operations\n- **🌐 Multi-Context Support**: Seamlessly switch between different Kubernetes clusters and contexts\n- **🔍 Advanced Diagnostics**: Intelligent pod failure detection and comprehensive troubleshooting\n- **📊 Node Health Monitoring**: Memory usage tracking and node health assessment\n- **⚡ FastAPI Backend**: High-performance async API with automatic OpenAPI documentation\n- **🤖 MCP Compatible**: Full Model Context Protocol support for AI assistant integration\n- **🐳 Container Ready**: Production Docker image with security best practices\n- **📋 Flexible Configuration**: Environment variables, INI files, and CLI options\n- **🛡️ Safe Operations**: Comprehensive input validation\n\n## 📋 Prerequisites\n\n- Python 3.8+\n- `kubectl` installed and configured\n- Access to a Kubernetes cluster\n- Valid kubeconfig file\n\n## 🛠️ Installation\n\n### Option 1: Docker (Recommended)\n\n```bash\n# Pull the latest image\ndocker pull pmithil7/kube-mcp-server:latest\n\n# Run with your kubeconfig mounted\ndocker run -p 8000:8000 \\\n  -v ~/.kube/config:/root/.kube/config:ro \\\n  pmithil7/kube-mcp-server:latest\n```\n\n### Option 2: From Source\n\n```bash\ngit clone https://github.com/pmithil7/kube-mcp-server.git\ncd kube-mcp-server\npip install -r requirements.txt\npython kubectl_mcp-server.py\n```\n\n### Option 3: pip install (Coming Soon)\n\n```bash\npip install kube-mcp-server\n```\n\n## 🚦 Quick Start\n\n### 1. Start the MCP Server\n\n```bash\n# Basic start (uses default kubeconfig)\npython kubectl_mcp-server.py\n\n# With custom port\nuvicorn kubectl_mcp-server:app --host 0.0.0.0 --port 8000\n\n# Docker with custom kubeconfig path\ndocker run -p 8000:8000 -v /path/to/kubeconfig:/root/.kube/config pmithil7/kube-mcp-server\n```\n\n### 2. Configure with Claude Desktop\n\nAdd to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"kube-mcp-server\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-v\", \"/Users/yourname/.kube/config:/root/.kube/config:ro\",\n        \"-p\", \"8000:8000\",\n        \"pmithil7/kube-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\n### 3. Start Managing Your Cluster with AI\n\nAsk Claude natural language questions like:\n- \"Show me all failing pods across all namespaces\"\n- \"What's wrong with my frontend deployment in production?\"\n- \"Find nodes with high memory usage above 80%\"\n- \"Troubleshoot the nginx pod in default namespace\"\n- \"Restart the api-gateway deployment\"\n- \"Switch to the staging cluster context\"\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# Kubeconfig location\nexport KUBECONFIG=/path/to/your/kubeconfig\n\n# Temp directory for processing\nexport MCP_TEMP_DIR=/tmp/kube-mcp\n\n# Slack integration (optional)\nexport SLACK_USER_ID=your-slack-user-id\n```\n\n### Vault Integration (Enterprise)\n\nFor secure kubeconfig management, place your kubeconfig in an INI format at:\n```\n/vault/secrets/kubectl.ini\n```\n\nThe server will automatically detect and use this configuration.\n\n### Security Controls\n\nThe server includes a built-in blocklist for destructive operations:\n- `delete`, `drain`, `cordon`, `uncordon`\n- `label`, `annotate`, `taint`\n- `apply`, `patch`, `replace`, `edit`, `set`\n\nTo modify the blocklist, edit the `DESTRUCTIVE_COMMAND_BLOCKLIST` in the source code.\n\n## 📚 API Endpoints\n\n### Core Operations\n- `POST /mcp/get_pods` - List all pods in a namespace\n- `POST /mcp/get_failing_pods` - Find problematic pods with intelligent failure detection\n- `POST /mcp/describe_pod` - Get detailed pod information\n- `POST /mcp/get_pod_logs` - Retrieve pod logs (last 50 lines)\n- `POST /mcp/troubleshoot_pod` - Comprehensive pod diagnostics\n\n### Deployment Management  \n- `POST /mcp/get_deployments` - List deployments\n- `POST /mcp/restart_deployment` - Rolling restart of deployments\n\n### Cluster Health\n- `POST /mcp/get_unhealthy_nodes` - Find nodes not in Ready state\n- `POST /mcp/get_nodes_by_memory` - Identify high memory usage nodes\n\n### Advanced Operations\n- `POST /mcp/execute_kubectl` - Execute custom kubectl commands (with safety controls)\n\n### Request Format\n\nAll endpoints expect a JSON body with this structure:\n\n```json\n{\n  \"entities\": {\n    \"namespace\": \"default\",\n    \"pod_name\": \"nginx-pod\",\n    \"deployment_name\": \"api-server\", \n    \"kube_context\": \"production-cluster\",\n    \"memory_threshold_percent\": 80,\n    \"command\": \"get services\",\n    \"args\": [\"-o\", \"wide\"]\n  }\n}\n```\n\n## 🔒 Security Considerations\n\n- **RBAC**: Ensure your kubeconfig has appropriate permissions\n- **Network Security**: Run on localhost by default\n- **Authentication**: Inherits kubectl authentication\n\n## 🐳 Docker Usage\n\n```bash\n# Run with mounted kubeconfig\ndocker run -p 8000:8000 -v ~/.kube/config:/root/.kube/config pmithil7/kube-mcp-server\n\n```\n\n## 🔌 Integration Examples\n\n### With Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"kubernetes\": {\n      \"command\": \"kube-mcp-server\",\n      \"args\": [\"--port\", \"8000\"],\n      \"env\": {\n        \"KUBECONFIG\": \"/path/to/your/kubeconfig\"\n      }\n    }\n  }\n}\n```\n\n### With Cursor IDE\n\nInstall as MCP server and configure in Cursor settings.\n\n### Programmatic Usage\n\n```python\nfrom kube_mcp_server import KubeMCPServer\n\nserver = KubeMCPServer(\n    kubeconfig_path=\"/path/to/kubeconfig\",\n    read_only=True\n)\nserver.start()\n```\n\n## 🧪 Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/pmithil7/kube-mcp-server.git\ncd kube-mcp-server\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements-dev.txt\npip install -e .\n\n# Run tests\npytest\n\n# Run linting\nblack .\nflake8 .\nmypy .\n```\n\n### Project Structure\n\n```\nkube-mcp-server/\n├── src/\n│   └── kube_mcp_server/\n│       ├── __init__.py\n│       ├── main.py\n│       ├── server.py\n│       ├── handlers/\n│       └── utils/\n├── tests/\n├── docs/\n├── docker/\n├── requirements.txt\n├── requirements-dev.txt\n├── setup.py\n├── pyproject.toml\n├── README.md\n├── CONTRIBUTING.md\n├── CHANGELOG.md\n└── LICENSE\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## 📖 Documentation\n\n- [API Documentation](docs/api.md)\n- [Configuration Guide](docs/configuration.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Examples](docs/examples/)\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Connection Refused**\n```bash\n# Check if kubectl works\nkubectl cluster-info\n\n# Verify kubeconfig\nkubectl config current-context\n```\n\n**Permission Denied**\n```bash\n# Check RBAC permissions\nkubectl auth can-i get pods\nkubectl auth can-i create deployments\n```\n\n**Server Won't Start**\n```bash\n# Check port availability\nlsof -i :8000\n\n# Enable debug logging\nkube-mcp-server --log-level DEBUG\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) specification\n- [FastAPI](https://fastapi.tiangolo.com/) framework\n- [Kubernetes](https://kubernetes.io/) community\n- All contributors and maintainers\n\n## 📊 Project Status\n\n![GitHub stars](https://img.shields.io/github/stars/pmithil7/kube-mcp-server)\n![GitHub issues](https://img.shields.io/github/issues/pmithil7/kube-mcp-server)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/pmithil7/kube-mcp-server)\n\n---\n\n**Made with ❤️ by [pmithil7](https://github.com/pmithil7)**\n\nFor questions or support, please [open an issue](https://github.com/pmithil7/kube-mcp-server/issues) or join our [discussions](https://github.com/pmithil7/kube-mcp-server/discussions).\n"}