gnosis-docker by kordless - MCP Server

Gnosis Docker

A Flask async server that exposes Docker management endpoints for MCP (Model Context Protocol) integration with Claude Desktop and Claude Code. This server communicates with the Docker daemon via Docker socket mounting, enabling comprehensive container management through AI assistants.

Features

Full Docker container management (list, start, stop, restart, remove)
Docker image management (list, pull, remove, build)
Container logs streaming and stats monitoring
Container inspection and health checks
Docker build triggers for Gnosis projects
Async Flask server with proper error handling
Security middleware for local-only access
MCP tools for AI assistant integration

Prerequisites and Setup

Windows with WSL2 (Recommended)

Gnosis Docker works best on Windows using WSL2 with Docker Desktop, as it provides native Docker socket access:

1. Install WSL2

# Run as Administrator in PowerShell
wsl --install
# Restart your computer

2. Install Docker Desktop

Download Docker Desktop from https://www.docker.com/products/docker-desktop/
During installation, ensure "Use WSL 2 based engine" is selected
Start Docker Desktop

3. Configure Docker Desktop for WSL2

# Run the setup helper script
.\setup-docker-desktop.ps1

Or manually configure:

Open Docker Desktop Settings
Go to General tab → Enable "Use WSL 2 based engine"
Go to Resources → WSL Integration → Enable integration with your WSL2 distro
Optional for development: In General tab → Enable "Expose daemon on tcp://localhost:2375 without TLS"
Click Apply & Restart

4. Verify Docker Socket Access

In WSL2:

# Check if Docker socket is accessible
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker 0 [date] /var/run/docker.sock

# Test Docker connection
docker version

Windows without WSL2 (Limited)

For development without WSL2, you can use Docker Desktop's TCP endpoint:

Enable TCP endpoint in Docker Desktop (Settings → General → "Expose daemon on tcp://localhost:2375")
Set environment variable: $env:DOCKER_HOST = "tcp://localhost:2375"
Run: .\setup-docker-desktop.ps1 to verify setup

Note: This method has limitations and security considerations. WSL2 is strongly recommended.

Docker Socket Communication

Gnosis Docker uses Docker socket mounting to communicate with the Docker daemon:

WSL2: Uses Unix socket /var/run/docker.sock (mounted into containers)
TCP: Uses tcp://localhost:2375 (for development only)
Security: The server validates all container operations and mounts

Directory Structure

gnosis-docker/
├── deploy.ps1              # Single deployment script for all environments
├── deploy-wsl2.sh          # WSL2 deployment script
├── requirements.txt        # Python dependencies
├── setup.ps1               # Initial setup script
├── setup-docker-desktop.ps1 # Docker Desktop configuration helper
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Local development with Redis
├── .env.example           # Environment variable template
├── .gitignore            # Git ignore file
├── README.md             # This file
├── WSL2_README.md        # WSL2-specific documentation
├── app.py                # Main Flask application
├── core/                 # Core application modules
│   ├── __init__.py
│   ├── docker_manager.py  # Docker operations handler
│   ├── auth.py           # Authentication middleware
│   ├── config.py         # Configuration management
│   ├── validation.py     # Container security validation
│   └── utils.py          # Utility functions
├── tests/                # Test suite
│   ├── __init__.py
│   └── test_docker_api.py
├── mcp/                  # MCP Tools Directory
│   ├── README.md         # MCP tools documentation
│   ├── requirements.txt  # MCP-specific dependencies
│   ├── setup.py          # MCP tools setup script
│   ├── gnosis_docker_mcp.py    # Docker management MCP tool
│   ├── file_manager_mcp.py     # File operations MCP tool
│   └── example_utilities_mcp.py # Example MCP tool
└── cleanup_*.py|ps1|sh   # Repository cleanup scripts

Quick Start

Deploy the Docker API Server

Windows WSL2 (Recommended)

# From WSL2 terminal
cd /mnt/c/Users/kord/Code/gnosis/gnosis-docker

# Make scripts executable
chmod +x deploy-wsl2.sh

# Deploy locally
./deploy-wsl2.sh

Windows PowerShell

# Initial setup (run once)
.\setup.ps1

# Windows - Deploy locally
.\deploy.ps1 -Target local

# Windows - Deploy to staging
.\deploy.ps1 -Target staging

# Windows - Deploy to production
.\deploy.ps1 -Target production

# Windows - Rebuild from scratch
.\deploy.ps1 -Target local -Rebuild

# Windows - Dry run (see what would happen)
.\deploy.ps1 -Target production -WhatIf

Use MCP Tools with AI Assistants

The /mcp directory contains ready-to-use MCP tools that integrate with Claude Code and Claude Desktop:

# Navigate to MCP tools
cd mcp

# Install dependencies
pip install -r requirements.txt

# Run setup and validation
python setup.py

# Configure with Claude Code
claude mcp add gnosis-docker python3 gnosis_docker_mcp.py

# Test the integration
claude
# Then try: "list docker containers", "check docker health"

See for complete MCP setup instructions.

API Endpoints

Container Management

GET /health - Health check
GET /api/containers - List all containers
GET /api/containers/<id> - Get container details
POST /api/containers/<id>/start - Start container
POST /api/containers/<id>/stop - Stop container
POST /api/containers/<id>/restart - Restart container
DELETE /api/containers/<id> - Remove container
GET /api/containers/<id>/logs - Get container logs
GET /api/containers/<id>/stats - Get container stats

Image Management

GET /api/images - List all images
POST /api/images/pull - Pull an image
DELETE /api/images/<id> - Remove an image

Project Operations

POST /api/build - Build a Gnosis project
POST /api/projects/<name>/deploy - Deploy a project

MCP Integration

This server provides Docker management capabilities to AI assistants through MCP tools:

Available MCP Tools

Gnosis Docker MCP (mcp/gnosis_docker_mcp.py)
- Complete Docker management through Claude Code/Desktop
- List, start, stop, restart containers
- Get container logs and statistics
- Manage Docker images
- Build and deploy Gnosis projects
File Manager MCP (mcp/file_manager_mcp.py)
- Cross-platform file operations
- Create, copy, move, delete files and directories
- Backup support for safe operations
Example Utilities MCP (mcp/example_utilities_mcp.py)
- Demonstrates MCP development patterns
- Basic utilities (echo, timestamps, calculations)
- Text analysis and system information

Configuration Methods

Claude Code (Recommended):

claude mcp add gnosis-docker python3 /path/to/gnosis-docker/mcp/gnosis_docker_mcp.py

Claude Desktop: Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gnosis-docker-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\gnosis-docker\\mcp\\gnosis_docker_mcp.py"]
    }
  }
}

Repository Maintenance

Clean Up Versioning Directories

This repository includes cleanup scripts to remove unwanted versioning directories and Python cache files:

# Python script (cross-platform)
python cleanup_comprehensive.py

# PowerShell script (Windows)
.\cleanup_comprehensive.ps1


# Bash script (Linux/WSL2)
./cleanup_quick.sh

These scripts will remove:

*_versions/ directories
__pycache__/ directories
*.pyc files
Update .gitignore with proper patterns

Environment Variables

FLASK_ENV - Environment (development/staging/production)
DOCKER_HOST - Docker daemon URL (default: unix:///var/run/docker.sock, or tcp://localhost:2375 for Windows)
API_KEY - Authentication key for production
REDIS_URL - Redis URL for caching (optional)
GNOSIS_DOCKER_URL - API endpoint URL (default: http://localhost:5680)

Security

Local-only access by default (binds to 127.0.0.1)
API key authentication for production deployments
Request validation and sanitization
Docker socket security with proper permissions and validation
CORS protection for web interfaces
Container parameter validation prevents dangerous operations
Volume mount restrictions limit filesystem access

Development

Running Locally

# Install dependencies
pip install -r requirements.txt

# Or use setup script
.\setup.ps1

# Run in development mode
python app.py


# Run tests
python -m pytest tests/

# Test API endpoints
python test_api.py

Docker Development

# Build container
docker build -t gnosis-docker .

# Or use deployment script
.\deploy.ps1 -Target local

# Run with Docker Compose
docker-compose up -d


# View logs
docker-compose logs -f gnosis-docker

Integration with Gnosis Ecosystem

This Docker controller is designed to work with other Gnosis components:

Gnosis Wraith - Web crawling and data extraction
Gnosis Mystic - Function interception and analysis
Gnosis Stream - Data processing and streaming
Gnosis Evolve - Development tools and utilities

The MCP tools provide a unified interface for AI assistants to manage the entire Gnosis ecosystem through Docker containers.

API Usage Examples

List Running Containers

curl http://localhost:5680/api/containers

Start a Container

curl -X POST http://localhost:5680/api/containers/mycontainer/start

Get Container Logs

curl http://localhost:5680/api/containers/mycontainer/logs?tail=100

Build a Gnosis Project

curl -X POST http://localhost:5680/api/build \
  -H "Content-Type: application/json" \
  -d '{"project": "gnosis-wraith", "tag": "latest"}'

Troubleshooting

Common Issues

Docker daemon not accessible in WSL2
- Check Docker Desktop is running
- Verify WSL2 integration is enabled in Docker Desktop
- Check Docker socket exists: ls -la /var/run/docker.sock
- Restart Docker Desktop and try again
Docker daemon not accessible on Windows
- Ensure Docker Desktop is running
- Check if TCP endpoint is enabled (Settings → General)
- Verify DOCKER_HOST environment variable
- Try running: .\setup-docker-desktop.ps1
"Cannot connect to Docker daemon" errors
- WSL2: Check that Docker socket is mounted: docker version
- Windows: Verify TCP endpoint: curl http://localhost:2375/version
- Check firewall settings
- Ensure Docker Desktop has started completely
Container fails to start
- Check Docker logs: docker-compose logs gnosis-docker
- Verify port 5680 is not in use: netstat -an | findstr 5680
- Check volume mounts in docker-compose.yml
Port 5680 already in use
- Stop existing instances
- Change port in deployment scripts
- Check for conflicting services
MCP tools not connecting
- Verify API server is running on localhost:5680
- Check firewall settings
- Ensure MCP dependencies are installed
Path issues with double slashes
- Use single backslashes in Windows paths
- WSL2 paths should use /mnt/c/ prefix
- Docker-compose uses Linux-style paths inside containers
- Check docker-compose.yml volume mappings

Logs and Debugging

# Check API server logs
docker-compose logs gnosis-docker

# Enable debug logging
export FLASK_ENV=development  # WSL2
$env:FLASK_ENV = "development"  # PowerShell
python app.py

# Test API health
curl http://localhost:5680/health

# Test Docker socket access (WSL2)
docker version
ls -la /var/run/docker.sock

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Update documentation
Submit a pull request

License

This project is part of the Gnosis ecosystem and follows the same licensing terms.