# ContainMind 🐋🧠

![alt text](/assets/image.png)

**A Universal Container Management MCP Server for Intelligent Container Operations**

ContainMind is an MCP (Model Context Protocol) server that provides AI assistants with powerful container management capabilities across multiple container runtimes. It enables seamless inspection, monitoring, and analysis of containerized environments through natural language interactions.

## 🎯 What is ContainMind?

ContainMind bridges the gap between AI assistants (like Claude) and container runtimes, allowing you to manage and analyze your containers using conversational interfaces. It's a unified API that works with multiple container engines, providing real-time insights and automation capabilities.

## 🔥 Problem It Solves

### The Challenge
Modern containerized applications often face these issues:
- **Fragmented tooling**: Different commands for Docker, Podman, and other runtimes
- **Complex debugging**: Diving through logs and metrics across multiple containers
- **Performance visibility**: Difficult to get quick insights into resource usage
- **Manual inspection**: Time-consuming manual checks for container health and configuration
- **Context switching**: Jumping between CLI tools and monitoring dashboards

### The Solution
ContainMind provides:
- **Unified interface** across Docker and Podman (with more runtimes coming)
- **AI-powered analysis** through natural language queries
- **Real-time monitoring** with easy-to-parse metrics
- **Automated diagnostics** for troubleshooting container issues
- **Single entry point** for all container operations

## 🚀 Features

### Multi-Runtime Support
- ✅ **Docker** - Full support for Docker Engine
- ✅ **Podman** - Complete Podman compatibility
- 🔄 **Auto-detection** - Automatically detects and connects to available runtime
- 🔌 **Pluggable architecture** - Easy to extend for additional runtimes

### Comprehensive Container Operations

#### 📦 Resource Discovery
- List all containers (running and stopped)
- List container images
- List volumes and their mount points
- List networks and connected containers

#### 🔍 Deep Inspection
- Detailed container analysis (configuration, environment, mounts)
- Real-time resource statistics (CPU, memory, network I/O)
- Container logs with configurable tail length
- System-wide information and capacity

#### ⚡ Performance Monitoring
- CPU usage percentage
- Memory usage and limits
- Network throughput (RX/TX)
- Parallel stats collection for multiple containers

## 🛠️ Available Tools

| Tool | Description | Use Case |
|------|-------------|----------|
| `initialize_connection` | Connect to container runtime | Initial setup, auto-detect or specify runtime |
| `list_all_containers` | List containers | Quick overview of all/running containers |
| `list_all_images` | List images | Check available images and sizes |
| `list_all_volumes` | List volumes | Identify storage usage and orphaned volumes |
| `list_all_networks` | List networks | Network topology and connectivity |
| `analyze_container` | Deep container inspection | Debug configuration, check mounts and env vars |
| `get_container_stats` | Resource usage metrics | Performance monitoring and optimization |
| `get_container_logs` | Retrieve container logs | Troubleshoot application issues |
| `get_system_info` | System information | Check overall capacity and utilization |

## 💡 How ContainMind Helps

### 1. **Issue Analysis**
**Scenario**: Your application is crashing
```
You: "Why is my mongo_local_standard container showing high memory usage?"
AI: [Uses get_container_stats + analyze_container]
    "The container is using 89% of its 2GB memory limit. 
     Checking the configuration... no memory limit set in docker-compose.
     Recommendation: Set explicit memory limits and check for memory leaks."
```

### 2. **Performance Tuning**
**Scenario**: Optimizing resource allocation
```
You: "Which containers are using the most CPU?"
AI: [Uses get_container_stats with all_running=True]
    "Analysis of running containers:
     1. kafka-1: 45% CPU - consider adding more brokers
     2. redis-server: 12% CPU - within normal range
     Recommendation: Kafka is CPU-bound, consider horizontal scaling."
```

### 3. **Quick Diagnostics**
**Scenario**: Container won't start
```
You: "Check why weaviate_db failed to start"
AI: [Uses get_container_logs + analyze_container]
    "Log analysis shows port 8080 binding failure.
     Inspecting configuration... port already in use by another service.
     Recommendation: Change port mapping or stop conflicting service."
```

### 4. **Resource Cleanup**
**Scenario**: Disk space management
```
You: "Show me unused volumes taking up space"
AI: [Uses list_all_volumes + list_all_containers]
    "Found 45 anonymous volumes not attached to any containers.
     Total reclaimable space: ~3.2 GB
     Safe to remove: [lists volume IDs]"
```

### 5. **Health Monitoring**
**Scenario**: Proactive monitoring
```
You: "Give me a health report of my container environment"
AI: [Uses get_system_info + get_container_stats]
    "System Health Report:
     - 7 total containers (1 running, 6 stopped)
     - Memory: 8.2GB / 16GB used (51%)
     - CPU: Normal load across running containers
     - Network: No bottlenecks detected
     Alerts: 6 stopped containers may need attention."
```

### 6. **Configuration Auditing**
**Scenario**: Security and best practices
```
You: "Check environment variables for containers with sensitive data"
AI: [Uses analyze_container for each container]
    "Security audit complete:
     - mongo_local_standard: Contains DB credentials in env vars
     - redis-server: No authentication configured
     Recommendation: Use Docker secrets or external secret management."
```

## 📋 Installation & Setup

### Prerequisites
- Python 3.8+
- Docker or Podman installed
- Access to container runtime socket

### Install Dependencies
```bash
pip install -r requirements.txt
```

### Run the Server
```bash
python containmind.py
```

The server starts on `http://127.0.0.1:8081` by default.

### Configure with Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json

{"mcpServers": {
"docker-Mcp": {
    "command": "uv",
    "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "path\to\proxy.py" 
    ],
    "env": {},
    "transport": "stdio"
}

    }
    
}
```

## 🔧 Usage Examples

### Auto-detect Runtime
```python
# ContainMind automatically detects Docker or Podman
initialize_connection()
```

### Specify Runtime
```python
# Force Docker
initialize_connection(backend="docker")

# Force Podman
initialize_connection(backend="podman")

# Custom socket
initialize_connection(base_url="unix:///run/podman/podman.sock")
```

### Get Container Stats
```python
# Single container
get_container_stats(container_id="mongo_local_standard")

# All running containers
get_container_stats(all_running=True, parallel=True)
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│         AI Assistant (Claude)           │
└────────────────┬────────────────────────┘
                 │ MCP Protocol
┌────────────────▼────────────────────────┐
│          ContainMind Server             │
│  ┌─────────────────────────────────┐   │
│  │    Tool Interface Layer          │   │
│  └──────────────┬──────────────────┘   │
│  ┌──────────────▼──────────────────┐   │
│  │   Container Inspector            │   │
│  └──────────────┬──────────────────┘   │
│  ┌──────────────▼──────────────────┐   │
│  │   Backend Abstraction Layer      │   │
│  │  ┌────────┐      ┌────────┐     │   │
│  │  │ Docker │      │ Podman │     │   │
│  │  └───┬────┘      └───┬────┘     │   │
│  └──────┼───────────────┼──────────┘   │
└─────────┼───────────────┼──────────────┘
          │               │
    ┌─────▼─────┐   ┌────▼─────┐
    │  Docker   │   │  Podman  │
    │  Engine   │   │  Runtime │
    └───────────┘   └──────────┘
```

## 🔐 Security Considerations

- ContainMind requires access to the container runtime socket
- Runs with the same permissions as the user/process executing it
- No authentication layer (relies on MCP transport security)
- Recommended: Use in trusted environments or add authentication

## 🚧 Roadmap

- [ ] Container lifecycle management (start/stop/restart)
- [ ] Image building and management
- [ ] Volume management operations
- [ ] Network configuration tools
- [ ] Container health checks
- [ ] Web UI dashboard

## 🤝 Contributing

Contributions are welcome! Areas for improvement:
- Additional container runtime support
- Enhanced metrics collection
- Performance optimizations
- Documentation improvements

## 📄 License
This project is licensed under the MIT License.

## 🙏 Acknowledgments

Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Docker SDK for Python](https://docker-py.readthedocs.io/) - Container API client
- [Anthropic Claude](https://www.anthropic.com/) - AI assistant integration

---

**ContainMind** - Making container management conversational, intelligent, and efficient. 🚀