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

Tool	Description
build_image	Build Docker image from Dockerfile
pull_image	Pull Docker image from registry
remove_image	Remove Docker image
list_resources	List containers and images

Container Operations

Tool	Description
run_container	Start container from image (requires byagent_ prefix)
get_container_logs	Fetch container logs
stop_and_remove_container	Stop/remove container, optionally remove image
exec_in_container	Execute arbitrary command in container (requires byagent_ prefix)

Test Execution

Tool	Description
run_tests	Run tests inside container with optional file/folder upload

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

Platform	Folder Upload Method
Windows	docker cp
macOS/Linux	tar pipe (preferred), docker cp (fallback)

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