Chaos Mesh MCP Server

English | 中文

Chaos Mesh MCP Server

A Model Context Protocol (MCP) server for Chaos Mesh fault injection, optimized for AWS EKS environments with full namespace support.

Features

Pod Fault Injection: Kill pods, inject failures, stress CPU/memory
Network Chaos: Simulate network delays, partitions, bandwidth limits
Host-level Chaos: CPU/memory stress, disk operations on nodes
EKS Optimized: Enhanced support for AWS EKS with proper RBAC and authentication
Namespace Support: All tools support custom namespaces
Improved Error Handling: Detailed error messages and retry mechanisms
Health Monitoring: Built-in health checks and diagnostics
uvx Integration: Simplified installation and dependency management with uvx

EKS Authentication Methods

There are two ways to authenticate the MCP server with your EKS cluster:

Method 1: Static Service Account Token (Recommended)

Generated by running the setup script — produces a self-contained kubeconfig with a long-lived ServiceAccount token. No AWS CLI or IAM credentials required at runtime.

# Run once to create RBAC + generate kubeconfig
./setup-eks-permissions.sh

# Start the server with the generated kubeconfig
python server.py --kubeconfig ./chaos-mesh-mcp-kubeconfig

Pros: Portable, no AWS dependency at runtime, least-privilege permissions (Chaos Mesh only) Cons: Token has a fixed expiry (default 1 year), needs renewal

Method 2: Admin kubeconfig with exec-based Auth

If a cluster admin provides their kubeconfig (typically generated by aws eks update-kubeconfig), the server can use it directly. This format uses aws eks get-token to obtain a token on each request.

# Start the server with an admin-provided kubeconfig
python server.py --kubeconfig /path/to/admin-kubeconfig

Or set via environment variable:

export KUBECONFIG=/path/to/admin-kubeconfig
python server.py

Requirements:

aws CLI must be installed on the machine running the MCP server
The machine must have valid AWS credentials (IAM role / ~/.aws/credentials)
The IAM identity must be mapped in the EKS aws-auth ConfigMap

Pros: Uses existing admin credentials, no extra setup needed Cons: Depends on AWS CLI + IAM credentials, admin-level permissions (overly broad)

Recommendation: Use Method 1 for production. Use Method 2 for quick testing when an admin kubeconfig is available.

Quick Start with uvx (Recommended)

1. One-time Environment Setup

cd /home/ec2-user/mcp-servers/Chaosmesh-MCP

# Run the uvx setup script (includes EKS permissions and kubeconfig generation)
./setup-uvx.sh

This script will:

Install Chaos Mesh (if not present)
Create necessary RBAC permissions
Generate chaos-mesh-mcp-kubeconfig file with service account credentials
Create environment configuration for uvx
Verify the setup

2. MCP Configuration

Add to your ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "chaosmesh-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/RadiumGu/Chaosmesh-MCP.git",
        "chaosmesh-mcp",
        "--kubeconfig",
        "/home/ec2-user/mcp-servers/Chaosmesh-MCP/chaos-mesh-mcp-kubeconfig",
        "--skip-env-check",
        "--transport",
        "stdio"
      ],
      "env": {
        "KUBECONFIG": "/home/ec2-user/mcp-servers/Chaosmesh-MCP/chaos-mesh-mcp-kubeconfig",
        "AWS_REGION": "us-east-2"
      },
      "autoApprove": [],
      "disabled": false,
      "transportType": "stdio"
    }
  }
}

3. Start Using

Restart your Amazon Q CLI session:

# Exit current session
/quit

# Restart
q chat

The MCP server will now run automatically via uvx when needed!

Alternative: Manual Setup (Legacy)

If you prefer the traditional approach or need to troubleshoot:

1. Clone and Setup Environment

git clone https://github.com/RadiumGu/Chaosmesh-MCP.git
cd Chaosmesh-MCP/
uv venv
source .venv/bin/activate
uv sync

2. Generate Kubeconfig

# Make the setup script executable
chmod +x setup-eks-permissions.sh

# Run the setup script to generate kubeconfig and configure permissions
./setup-eks-permissions.sh

3. Start MCP Server

# Use the generated kubeconfig
export KUBECONFIG=./chaos-mesh-mcp-kubeconfig
uv run python server.py --kubeconfig ./chaos-mesh-mcp-kubeconfig

uvx vs Manual Installation

uvx Advantages (Recommended):

✅ Automatic dependency management: No need to manage Python environments
✅ Direct from Git: Always uses latest version from repository
✅ Version isolation: Clean environment for each run
✅ Simplified maintenance: No manual virtual environment management
✅ One-time setup: Just run ./setup-uvx.sh once

Manual Installation:

⚠️ Requires manual dependency management
⚠️ Need to sync repository updates manually
⚠️ Virtual environment maintenance required
✅ More control over the environment
✅ Easier for development and debugging

Troubleshooting Setup

If you encounter issues:

Missing kubeconfig file: Run ./setup-uvx.sh or ./setup-eks-permissions.sh
Permission errors: Ensure your AWS credentials have EKS access
Connection issues: Verify kubectl can access your cluster
uvx issues: Check if uvx is installed: uvx --version

For detailed setup instructions, see SETUP.md and UVX-USAGE.md.

Namespace Support

All Chaos Mesh MCP tools now support specifying custom namespaces:

Available Tools with Namespace Support

pod_kill(service, duration, mode, value, namespace="default")
pod_failure(service, duration, mode, value, namespace="default")
pod_cpu_stress(service, duration, mode, value, container_names, workers, load, namespace="default")
pod_memory_stress(service, duration, mode, value, container_names, size, time, namespace="default")
container_kill(service, duration, mode, value, container_names, namespace="default")
network_partition(service, mode, value, direction, external_targets, namespace="default")
network_bandwidth(service, mode, value, direction, rate, limit, buffer, external_targets, namespace="default")
delete_experiment(type, name, namespace="default")
inject_delay_fault(service, delay, namespace="default")
remove_delay_fault(service, namespace="default")

New Namespace Management Tools

list_namespaces(): List all available namespaces
list_services_in_namespace(namespace="default"): List services in a specific namespace
health_check(): Check system health

Example Usage

# List all namespaces
namespaces = list_namespaces()

# List services in votingapp namespace
services = list_services_in_namespace("votingapp")

# Kill 50% of votingapp pods in votingapp namespace for 30 seconds
pod_kill(
    service="votingapp",
    duration="30s", 
    mode="fixed-percent",
    value="50",
    namespace="votingapp"
)

# Apply CPU stress in production namespace
pod_cpu_stress(
    service="api-service",
    duration="2m",
    mode="fixed",
    value="2",
    container_names=["api"],
    workers=2,
    load=80,
    namespace="production"
)

# Check system health
health_status = health_check()

Installation

Prerequisites

uvx: Python package runner (recommended)
kubectl: Configured for your cluster
Helm: For Chaos Mesh installation
AWS CLI: For EKS environments
Python 3.10+: Required by uvx

uvx Installation (Recommended)

# Install uvx if not already installed
pip install uvx

# Run one-time setup
cd /home/ec2-user/mcp-servers/Chaosmesh-MCP
./setup-uvx.sh

uvx will automatically handle all Python dependencies:

chaos-mesh>=1.2.13
kubernetes>=32.0.1
mcp[cli]>=1.7.1

Manual Installation (Alternative)

# Clone repository
git clone https://github.com/RadiumGu/Chaosmesh-MCP.git
cd Chaosmesh-MCP/

# Setup Python environment
uv venv
source .venv/bin/activate
uv sync

# Install dependencies manually
pip install chaos-mesh>=1.2.13 kubernetes>=32.0.1 mcp[cli]>=1.7.1

Configuration

uvx Configuration (Recommended)

For uvx-based deployment, use the automated setup:

./setup-uvx.sh

This script will:

Install Chaos Mesh if not present
Create necessary RBAC permissions with cross-namespace support
Generate a service account kubeconfig
Create environment configuration for uvx
Verify the setup

EKS Environment (Manual)

For manual AWS EKS cluster setup:

./setup-eks-permissions.sh

This script will:

Install Chaos Mesh if not present
Create necessary RBAC permissions with cross-namespace support
Generate a service account kubeconfig
Verify the setup

Manual Configuration

Install Chaos Mesh:

helm repo add chaos-mesh https://charts.chaos-mesh.org
helm install chaos-mesh chaos-mesh/chaos-mesh -n chaos-mesh --create-namespace

Apply RBAC:
```
kubectl apply -f rbac-config.yaml
```

Troubleshooting

Common Issues

uvx Command Not Found:
```
pip install uvx
```
Connection Timeouts:
- Check Chaos Mesh installation
- Verify RBAC permissions
- Use health_check() tool
Permission Denied:
- Apply RBAC configuration
- Use service account kubeconfig
- Re-run ./setup-uvx.sh
Service Not Found:
- Verify service name and namespace
- Use list_services_in_namespace() to check available services
- Check label selectors
Namespace Issues:
- Use list_namespaces() to see available namespaces
- Ensure namespace exists before running experiments
uvx Installation Issues:
- Check if kubeconfig exists: ls -la /home/ec2-user/mcp-servers/Chaosmesh-MCP/chaos-mesh-mcp-kubeconfig
- Verify Kubernetes connection: kubectl get pods -n chaos-mesh
- Re-run setup: ./setup-uvx.sh

Debug Mode

For uvx (automatic via MCP configuration):

"env": {
  "KUBECONFIG": "/home/ec2-user/mcp-servers/Chaosmesh-MCP/chaos-mesh-mcp-kubeconfig",
  "AWS_REGION": "us-east-2",
  "DEBUG": "true"
}

For manual mode:

python server.py --skip-env-check --kubeconfig ./chaos-mesh-mcp-kubeconfig

Logs

Check Chaos Mesh controller logs:

kubectl logs -n chaos-mesh -l app.kubernetes.io/name=chaos-mesh

Check experiments across namespaces:

kubectl get podchaos --all-namespaces

Migration from Manual to uvx

If migrating from manual installation, see MIGRATION-TO-UVX.md for detailed instructions.

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  Chaos Mesh MCP │────│   Kubernetes    │
│                 │    │     Server       │    │    Cluster      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                │
                       ┌──────────────────┐
                       │   Chaos Mesh     │
                       │   Controllers    │
                       └──────────────────┘

Security

Uses dedicated service account with minimal permissions
Supports cross-namespace operations with proper RBAC
Token-based authentication for EKS
Namespace isolation support
Audit logging support

Best Practices

Use service accounts: Avoid using personal credentials
Namespace isolation: Use different namespaces for different environments
Monitor experiments: Regularly check experiment status across namespaces
Clean up resources: Delete completed experiments promptly
Detailed logging: Enable verbose logging for troubleshooting

Contributing

Fork the repository
Create a feature branch
Make your changes
Test in EKS environment with multiple namespaces
Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

Check the troubleshooting section above
Review logs and health status
Consult the documentation:
Use namespace management tools for debugging
Check the GitHub Issues page

Documentation

README.md - This file, main documentation
SETUP.md - Detailed setup instructions
EKS-SETUP.md - EKS-specific setup guide
UVX-USAGE.md - uvx installation and usage guide
MIGRATION-TO-UVX.md - Migration from manual to uvx

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
.python-version		.python-version
EKS-SETUP.md		EKS-SETUP.md
MIGRATION-TO-UVX.md		MIGRATION-TO-UVX.md
README.md		README.md
README_zh.md		README_zh.md
SETUP.md		SETUP.md
UVX-USAGE.md		UVX-USAGE.md
fault_inject.py		fault_inject.py
kube.py		kube.py
pyproject.toml		pyproject.toml
rbac-config.yaml		rbac-config.yaml
server.py		server.py
services.json		services.json
setup-eks-permissions.sh		setup-eks-permissions.sh
setup-uvx.sh		setup-uvx.sh
test.py		test.py

Latest commit

History

Folders and files

Repository files navigation

Chaos Mesh MCP Server

Features

EKS Authentication Methods

Method 1: Static Service Account Token (Recommended)

Method 2: Admin kubeconfig with exec-based Auth

Quick Start with uvx (Recommended)

1. One-time Environment Setup

2. MCP Configuration

3. Start Using

Alternative: Manual Setup (Legacy)

1. Clone and Setup Environment

2. Generate Kubeconfig

3. Start MCP Server

uvx vs Manual Installation

uvx Advantages (Recommended):

Manual Installation:

Troubleshooting Setup

Namespace Support

Available Tools with Namespace Support

New Namespace Management Tools

Example Usage

Installation

Prerequisites

uvx Installation (Recommended)

Manual Installation (Alternative)

Configuration

uvx Configuration (Recommended)

EKS Environment (Manual)

Manual Configuration

Troubleshooting

Common Issues

Debug Mode

Logs

Migration from Manual to uvx

Architecture

Security

Best Practices

Contributing

License

Support

Documentation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages