Build and Run

# Clone the repository
git clone https://github.com/fabriziosalmi/nexus-mcp-server.git
cd nexus-mcp-server

# Build the Docker image
docker build -t nexus-mcp-server .

# Run the container
docker run -d \
  --name nexus-mcp \
  -p 9999:9999 \
  -v $(pwd)/safe_files:/app/safe_files:rw \
  -v $(pwd)/config.json:/app/config.json:ro \
  nexus-mcp-server

Start with Docker Compose

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f nexus-mcp

# Stop the service
docker-compose down

docker-compose.yml

services:
  nexus-mcp:
    build:
      context: .
      dockerfile: Dockerfile
    image: nexus-mcp-server:latest
    container_name: nexus-mcp-server
    
    # Expose HTTP API port
    ports:
      - "9999:9999"
    
    # Volume mounts for data persistence
    volumes:
      # Safe files directory for file operations
      - ./safe_files:/app/safe_files:rw
      # Configuration file (read-only)
      - ./config.json:/app/config.json:ro
      # Logs directory (optional)
      - ./logs:/app/logs:rw
    
    # Environment variables
    environment:
      - PYTHONUNBUFFERED=1
      - MCP_SERVER_NAME=NexusServer
      - MCP_SERVER_VERSION=2.0.0
      - LOG_LEVEL=INFO
    
    # Health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9999/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    
    # Restart policy
    restart: unless-stopped

Multi-stage Build

FROM python:3.12-slim

# Metadata
LABEL maintainer="Nexus MCP Server"
LABEL description="Advanced, modular and configurable MCP server"
LABEL version="2.0.0"

# Environment variables
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

# Create non-root user for security
RUN groupadd -r nexus && useradd -r -g nexus -m nexus

# Install system dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    gcc \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create necessary directories
RUN mkdir -p safe_files logs && \
    chown -R nexus:nexus /app

# Switch to non-root user
USER nexus

# Expose port
EXPOSE 9999

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:9999/ || exit 1

# Default command
CMD ["python", "http_server.py"]

Docker Commands

# View running containers
docker ps

# View all containers
docker ps -a

# View container logs
docker logs nexus-mcp

# Follow logs in real-time
docker logs -f nexus-mcp

# Execute commands in running container
docker exec -it nexus-mcp bash

# Stop container
docker stop nexus-mcp

# Remove container
docker rm nexus-mcp

# Remove image
docker rmi nexus-mcp-server

Compose Management

# Start services in background
docker-compose up -d

# Start and rebuild
docker-compose up -d --build

# View service status
docker-compose ps

# View logs for all services
docker-compose logs

# View logs for specific service
docker-compose logs nexus-mcp

# Stop services
docker-compose stop

# Stop and remove containers
docker-compose down

# Stop and remove containers + volumes
docker-compose down -v

# Scale service (if configured)
docker-compose up -d --scale nexus-mcp=3

Important Volumes

• safe_files/ - File operations directory (read-write)
• config.json - Server configuration (read-only)
• logs/ - Application logs (read-write, optional)

Configuration Options

Resource Limits Example

services:
  nexus-mcp:
    # ... other configuration ...
    
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Health Check Endpoint

# Manual health check
curl http://localhost:9999/

# Expected response
{
  "status": "healthy",
  "message": "Nexus MCP Server Enhanced API is running",
  "tools_count": 39,
  "server_info": {
    "name": "NexusServer-Enhanced",
    "version": "3.0.0",
    "type": "HTTP-MCP Bridge"
  }
}

Common Issues

# Change port mapping
docker run -p 8888:9999 nexus-mcp-server

# Or in docker-compose.yml
ports:
  - "8888:9999"

# Fix ownership
sudo chown -R $(id -u):$(id -g) safe_files logs

# Or use bind mounts with correct permissions
docker run -v $(pwd)/safe_files:/app/safe_files:rw ...

# View container logs
docker logs nexus-mcp

# Run in foreground for debugging
docker run --rm -it nexus-mcp-server