docker-agent-backend

Docker Agent Backend exposes REST APIs and WebSocket streams to manage and monitor Docker containers remotely. It includes an MCP (Model Context Protocol) surface that lets AI assistants like Claude or Cursor interact with Docker through a set of predefined tools such as listing containers, getting container details, streaming logs, and retrieving images. You can authenticate via JWT and use the provided endpoints under /api/v1 to perform typical container operations, plus the MCP endpoints at /mcp/sse and /mcp/messages/ to exchange structured commands. Real-time capabilities include WebSocket streams for logs, stats, and events, enabling reactive integrations with dashboards or assistants. Ensure you provide a valid Bearer token when calling protected endpoints and supply the MCP token on the MCP SSE and message endpoints when using the MCP tools.

Prerequisites: Docker and Docker Compose installed on the host, and internet access. If you prefer local development, Python and dependencies listed in requirements.txt are needed as an alternative to Docker-based setup.

Option A: Docker Compose (recommended)

1. Clone the repository:

git clone https://github.com/ahmed-gelemli/docker-agent-backend.git
cd docker-agent-backend

2. Create environment file with required credentials:

cat > .env << EOF
SECRET_KEY=$(openssl rand -base64 32)
API_USERNAME=admin
API_PASSWORD=your_secure_password
MCP_ENABLED=true
MCP_API_KEY=your-mcp-api-key-at-least-16-chars
MCP_DEBUG=false
DEBUG=false
APP_NAME=Docker Agent
EOF

3. Start the stack (via Docker Compose):

docker compose up --build -d

Option B: Local development (non-Docker)

1. Install Python dependencies:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Create a .env file with the same keys as above, or configure environment variables in your shell.
3. Run the dev server:

python run.py

Prerequisites summary: Docker with Compose for the recommended path; Python 3.x and dependencies for local development; OpenSSL for generating SECRET_KEY; network access to pull Docker images. Ensure the MCP feature is enabled via MCP_ENABLED and provide a valid MCP_API_KEY if you intend to use MCP tools.

Tips and common issues: - If JWT validation fails, verify system clock synchronization between client and server. - Ensure MCP_API_KEY remains secret; rotate periodically. - For WebSocket streams, pass the JWT as a query parameter the same as described in the MCP section. - If rate limiting blocks legitimate requests during testing, temporarily adjust RATE_LIMIT_* values in .env or your deployment environment. - Use the health endpoints to verify container status and Docker connectivity before integrating with external tools. - The MCP surface exposes a stable set of tools; use the SSE endpoint at /mcp/sse to initialize the MCP session and then send messages to /mcp/messages/.