local-docker-mcp

A Python MCP (Model Context Protocol) server that provides Docker container management and test execution capabilities via FastMCP. Runs as an HTTP server on port 8000 at path /local-docker/mcp/.

Features

• Docker Image Management: Build, pull, list, and remove Docker images

• Container Operations: Run, stop, remove containers; fetch logs; execute commands

• Test Execution: Run tests inside containers with automatic file/folder upload

• Cross-Platform: Works on Windows, macOS, and Linux with platform-appropriate upload strategies

• MCP Protocol: Exposes all functionality as MCP tools for LLM consumption

Tech Stack

• Python ≥3.14

• FastMCP ≥3.4.2 - MCP server framework

• docker ≥7.1.0 - Docker SDK for Python

• uv - Dependency management

Project Structure

local-docker-mcp/
├── main.py          # Main MCP server entry point (single file)
├── pyproject.toml   # Project config & dependencies
├── uv.lock          # Locked dependencies
├── .python-version  # Python version pin
├── .gitignore
└── README.md

Quick Start

Prerequisites

• Python ≥3.14

• Docker installed and running

• uv package manager

Installation

# Clone and navigate to project
cd local-docker-mcp

# Install dependencies
uv sync

# Run the MCP server
uv run main.py

The server starts at http://0.0.0.0:8000/local-docker/mcp/

Development

# Install in editable mode
uv pip install -e .

# Add a new dependency
uv add package-name
uv sync

Available MCP Tools

All tools are decorated with @mcp.tool() and exposed via the MCP protocol.

Image Management

Container Operations

Test Execution

run_tests Parameters

• container_name (required, must have prefix byagent_)

• container_tests_folder (required, absolute path in container)

• test_file (optional, specific test file)

• test_node_ids (optional, specific test node IDs)

• upload_from_folder / upload_from_files (mutually exclusive, for uploading test files)

• test_runner (default: pytest)

• test_runner_args (optional, additional test runner arguments)

• env_vars (optional, environment variables)

• timeout_seconds (optional, test timeout)

Upload Strategy

• upload_from_folder: Copies entire folder contents to container_tests_folder

• upload_from_files: Copies specific files to container_tests_folder

• Mutually exclusive — cannot use both

Architecture

Main Entry Point (main.py)

• FastMCP Server: Named "local-docker-mcp", runs on HTTP transport at 0.0.0.0:8000 with path /local-docker/mcp/

• Platform Detection: Detects OS at import time for cross-platform Docker commands

Key Components

1. _run(cmd, cwd, timeout) — Shell command runner with structured output and timeout handling

2. _fmt(res, label) — Formats command results into readable strings with success/failure icons

3. _upload_files_to_container(files, container_name, dest) — Cross-platform file upload via docker cp

4. _upload_folder_to_container(folder, container_name, dest) — Cross-platform folder upload:

   • Windows: Uses docker cp exclusively

   • macOS/Linux: Prefers tar pipe for permissions/symlinks, falls back to docker cp

Container Naming Convention

All container operations require the byagent_ prefix for container names (validated in tools).

Cross-Platform Support

License

[Add your license here]

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests (when available)

5. Submit a pull request