Kubectl Go MCP Server
MCP server for secure Kubernetes Interaction via kubectl commands. Enables AI assistants like GitHub Copilot to safely interact with K8s clusters with robust validation and security.
Installation
npx kubectl-go-mcp-serverAsk AI about Kubectl Go MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Kubectl Go MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
kubectl-go-mcp-server
A Model Context Protocol (MCP) server that provides Kubernetes cluster interaction capabilities through kubectl commands. This server enables MCP-compatible clients (like VS Code with Copilot) to execute kubectl commands and retrieve Kubernetes cluster information safely and securely.
Features
- Kubernetes Integration: Execute kubectl commands through MCP interface
- Interactive Command Protection: Prevents execution of interactive commands that could hang
- Resource Modification Detection: Identifies commands that modify cluster resources
- Robust Security: Multiple validation layers to prevent command injection and unsafe operations
- Configurable Kubeconfig: Support for custom kubeconfig paths
- Standard Go Project Layout: Following Go best practices for maintainability
- Cobra CLI Integration: Professional command-line interface with subcommands
Architecture
kubectl-go-mcp-server acts as a bridge between MCP clients (like VS Code with Copilot) and Kubernetes clusters through kubectl commands:
VS Code/Copilot β MCP Client β kubectl-go-mcp-server β kubectl β Kubernetes Cluster
Key Components
- MCP Server: Handles JSON-RPC communication and tool registration
- kubectl Tool: Validates and executes kubectl commands safely
- Security Layer: Prevents interactive commands and command injection
For detailed architecture information, see docs/architecture.md.
pkg/
βββ types/ # π§ Core interfaces and data structures
β βββ Tool # Interface for all MCP tools
β βββ Schema # JSON schema definitions
β βββ ExecResult # Command execution results
β
βββ kubectl/ # π― kubectl-specific implementation
β βββ KubectlTool # Main tool implementation
β βββ Validation # Command safety checks
β βββ Execution # kubectl command runner
β
internal/
βββ mcp/ # π MCP protocol implementation
β βββ Server # MCP server and protocol handling
β βββ Tools # Tool registry and management
β βββ Protocol # JSON-RPC message handling
β
βββ config/ # βοΈ Configuration management
βββ Config # Application configuration
βββ Defaults # Default settings
Extension Points
The architecture is designed for extensibility:
- New Tools: Implement the
Toolinterface to add new capabilities - Custom Validation: Add validation layers for specific use cases
- Protocol Extensions: Extend MCP handling for additional features
- Output Formatters: Add custom result processing
Performance Considerations
- Concurrent Safety: All components are designed for concurrent access
- Resource Management: Proper cleanup and resource disposal
- Timeout Handling: Configurable timeouts for all operations
- Memory Efficiency: Streaming and buffered I/O for large outputs
Installation
Prerequisites
- Go 1.23 or later
- kubectl installed and configured
- Access to a Kubernetes cluster
Build from Source
# Clone the repository
git clone https://github.com/Joelayo/kubectl-go-mcp-server.git
cd kubectl-go-mcp-server
# Build the binary
make build
# Or install directly
make install
Download Binary
Download the latest release from the releases page for your platform.
Usage
Standalone
# Run with default kubeconfig
./kubectl-go-mcp-server
# Run with custom kubeconfig
./kubectl-go-mcp-server --kubeconfig /path/to/kubeconfig
# Show version
./kubectl-go-mcp-server version
VS Code Integration
To use with VS Code and Copilot, add this MCP server to your VS Code settings:
{
"mcp": {
"servers": {
"kubectl-go-mcp-server": {
"type": "stdio",
"command": "/path/to/kubectl-go-mcp-server",
"env": {}
}
}
}
}
For platform-specific installation details, see the examples directory.
Available Tools
The MCP server provides the following tool:
kubectl
Execute kubectl commands with comprehensive validation and safety checks.
Parameters:
command(required): The complete kubectl command to execute (including 'kubectl' prefix)modifies_resource(optional): Indicates if the command modifies resources ("yes", "no", "unknown")
Example:
{
"name": "kubectl",
"arguments": {
"command": "kubectl get pods -o json",
"modifies_resource": "no"
}
}
Safety Features:
- Interactive Command Detection: Prevents hanging on interactive commands like
kubectl exec -it,kubectl edit,kubectl port-forward - Resource Modification Tracking: Automatically detects destructive operations
- Command Validation: Ensures only valid kubectl commands are executed
Security
This server implements multiple security layers including command validation, injection prevention, and interactive command blocking. For detailed security information, see:
- Security Overview - Technical security implementation details
- Security Policy - Vulnerability reporting and security best practices
Development
See CONTRIBUTING.md for development setup, workflow, and contribution guidelines.
Quick Start for Developers
# Install dependencies and build
make deps && make build
# Run tests
make test
# Format and lint code
make fmt && make lint
Troubleshooting
Common Issues
- Server not responding: Verify kubectl is installed and kubeconfig is accessible
- Interactive command errors: Use non-interactive alternatives (see Security Overview)
- Permission denied: Check kubectl permissions and cluster connectivity
For detailed debugging information, the server logs all tool calls, validation results, and errors.
Support
- Create an issue for bug reports or feature requests
- Check existing issues for known problems
- See CONTRIBUTING.md for development questions
License
This project is licensed under the MIT License - see the LICENSE file for details.
