Docker MCP Server

🚀 Docker MCP Server

A Model Context Protocol (MCP) server that empowers AI assistants and applications with Docker container execution capabilities. This server enables the isolated execution of commands and file operations within a containerized environment.

✨ Features

• Secure Command Execution: Execute shell commands within isolated Docker containers
• File Operations: Read, write, edit, and search for files inside containers
• Process Management: Track long - running processes through unique IDs
• Interactive Input: Send input to ongoing processes
• Smart Timeouts: Implement intelligent process timeout handling based on output activity

🏗️ Architecture

This MCP server serves as a bridge between MCP clients (such as Claude Code) and a Docker container environment:

MCP Client (Claude Code) ↔ MCP Server ↔ Docker Container (Debian + Node.js)
                                              ↓
                                        Host ./tmp directory

Core Components

• MCP Server (src/index.ts): A TypeScript server leveraging @modelcontextprotocol/sdk
• Docker Container: A Debian - based container equipped with Node.js and development tools
• File Mount: The host's ./tmp directory is mounted to the container's /app for data persistence
• Process Tracking: Background process management with unique IDs and monitoring

📦 Installation

Prerequisites

• Docker should be installed and running.
• Docker Compose is required for easy container management.
• Node.js (v18 or higher) is needed for the MCP server.
• npm is used for dependency management.

🚀 Quick Start

Option 1: Run with npx (Recommended)

# Run directly with npx (no installation needed)
npx docker-mcp-server

# Run with custom container name
npx docker-mcp-server --container-name my-container

# Show help and available options
npx docker-mcp-server --help

Prerequisites: Docker must be installed and running, and a container should be available.

Option 2: Install Globally

# Install globally
npm install -g docker-mcp-server

# Run from anywhere
docker-mcp-server --container-name my-container

Option 3: Development Setup

1. Clone and Setup

git clone <your-repository-url>
cd docker-mcp
npm install

2. Start the Environment

# Reset and start Docker environment
./reset-docker.sh

This script will:

• Stop any existing containers.
• Clean the /tmp directory.
• Start the container in the background.
• Provide an interactive shell.

3. Build and Run the MCP Server

# Build TypeScript
npm run build

# Start the MCP server (uses default container name: mcp-container)
npm start

# Start with a custom container name
npm start -- --container-name my-custom-container

# Or build and start in one command
npm run dev

# Build and start with custom container
npm run dev -- --container-name my-custom-container

💻 Usage Examples

CLI Usage

The MCP server supports the following command - line options:

# Show help and available options
node dist/index.js --help

# Start with default container name (mcp-container)
node dist/index.js

# Start with custom container name
node dist/index.js --container-name my-dev-container
node dist/index.js -c my-dev-container

# Show version
node dist/index.js --version

Container Name Configuration

You can configure the Docker container name in multiple ways:

1. Default: If no option is provided, it uses mcp-container.
2. CLI Argument: Use the --container-name or -c flag.
3. Multiple Instances: Run multiple MCP servers with different containers.

# Terminal 1: Development container
npm run dev -- --container-name dev-container

# Terminal 2: Testing container  
npm run dev -- --container-name test-container

# Terminal 3: Production container
npm run dev -- --container-name prod-container

MCP Client Configuration

To use this server with MCP clients like Claude Desktop, add the following configuration:

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest"
      ]
    }
  }
}

With custom container:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest",
        "--container-name", "my-dev-container"
      ]
    }
  }
}

Other MCP Clients

For other MCP clients, use the following command:

npx -y docker-mcp-server@latest

Prerequisites for MCP Usage

1. Docker container must be running:

   docker run -d --name mcp-container -v ./workspace:/app node:current-bookworm sleep infinity
   

2. Container should have your project files:

   • Mount your workspace directory to /app in the container.
   • Ensure the container has the necessary development tools installed.

3. Restart Claude Desktop after adding the configuration.

Verification

After configuration, Claude Desktop should show the Docker MCP server as connected, with access to all available tools for container - based development.

🛠️ Development Commands

Container Management

# Reset Docker environment (stops containers, cleans /tmp, restarts)
./reset-docker.sh

# Start container in background
docker-compose up -d

# Stop and remove containers
docker-compose down

# Interactive shell into container
docker exec -it mcp-container bash

Build and Run

# Compile TypeScript to JavaScript in /dist
npm run build

# Run the compiled MCP server
npm start

# Build and start in one command
npm run dev

🔧 Technical Details

Available MCP Tools

The server offers the following tools for MCP clients:

🚀 Command Execution

execute_command

Execute shell commands inside a Docker container

Execute any shell command within the container environment, accompanied by intelligent process tracking and timeout handling.

Parameters:

• command (string): The shell command to be executed in the container.
• rationale (string): An explanation of why this command is being executed.
• maxWaitTime (number, optional): The maximum number of seconds to wait before returning to the agent (default: 20).

Features:

• Automatic backgrounding for long - running processes.
• Smart timeout based on output activity.
• A process ID is returned for monitoring.
• Real - time output capture.

check_process

Monitor background processes by ID

Check the status and output of background processes initiated by execute_command.

Parameters:

• processId (string): The process ID returned by a long - running command.
• rationale (string): An explanation of why you need to check this process.

Returns:

• Process status (running/completed).
• Current output (stdout/stderr).
• Exit code (if completed).
• Runtime duration.

send_input

Send input to running background processes

Send input data to interactive processes awaiting user input.

Parameters:

• processId (string): The process ID of the ongoing process.
• input (string): The input to be sent to the process.
• rationale (string): An explanation of why you need to send input to this process.
• autoNewline (boolean, optional): Whether to automatically add a newline (default: true).

📁 File Operations

file_read

Read files from container filesystem

Read file contents, with support for large files through offset and limit parameters.

Parameters:

• filePath (string): The path to the file to be read (relative to /app in the container).
• rationale (string): An explanation of why you need to read this file.
• offset (number, optional): The starting line number (0 - based, default: 0).
• limit (number, optional): The maximum number of lines to read (default: 2000).

Features:

• Line - numbered output (cat - n format).
• Support for large files with pagination.
• Binary file detection and rejection.
• Context - safe reading with limits.

file_write

Create or overwrite files in container

Write content to files, with safety checks and directory creation.

Parameters:

• filePath (string): The path to the file to be written (relative to /app in the container).
• content (string): The content to be written to the file.
• rationale (string): An explanation of why you need to write this file.

Safety Features:

• Automatic directory creation.
• Content length reporting.
• File existence validation.
• Safe content transmission.

Important: You MUST use file_read first before writing to understand the current state and context of the file.

file_edit

Perform exact string replacements in files

Edit files using precise string matching and replacement, with backup protection.

Parameters:

• filePath (string): The path to the file to be edited (relative to /app in the container).
• oldString (string): The exact text to be replaced.
• newString (string): The replacement text.
• rationale (string): An explanation of why you need to edit this file.
• replaceAll (boolean, optional): Whether to replace all occurrences (default: false).

Safety Features:

• Automatic backup creation before editing.
• Exact string matching requirement.
• Base64 encoding for safe text transmission.
• Backup restoration on failure.

Important: You MUST use file_read first to obtain the exact text to match and understand the file's current state.

file_ls

List directory contents with filtering

List files and directories with intelligent filtering and output limits.

Parameters:

• path (string, optional): The directory path to list (default: current directory).
• rationale (string): An explanation of why you need to list this directory.
• ignore (array of strings, optional): A list of glob patterns to ignore.

Features:

• Built - in ignore patterns (node_modules, .git, dist, etc.).
• Detailed file information (permissions, size, timestamps).
• Output limit (100 entries) with overflow notification.
• Smart pattern filtering.

file_grep

Search file contents with regex support

Search for patterns in files using powerful grep functionality, with result limits.

Parameters:

• pattern (string): The search pattern (supports regex).
• rationale (string): An explanation of why you need to search for this pattern.
• path (string, optional): The directory to search in (default: current directory).
• include (string, optional): A file pattern to include (e.g., '.js', '.{ts,tsx}').
• caseInsensitive (boolean, optional): Case - insensitive search (default: false).
• maxResults (number, optional): The maximum number of results to return (default: 100).

Features:

• Recursive directory search.
• File type filtering.
• Line number display.
• Result count limiting with overflow reporting.
• Regex pattern support.

Process Management

Commands are executed with intelligent timeout handling:

• Default timeout: 20 seconds of inactivity before backgrounding.
• Maximum timeout: An absolute limit of 10 minutes.
• Process tracking: Background processes are assigned unique IDs for monitoring.
• Smart waiting: Based on output activity rather than fixed intervals.

Example Process Flow

# Long-running command gets backgrounded automatically
process_id = execute_command("npm install", "Installing dependencies")

# Check status later
check_process(process_id, "Checking installation progress")

# Send input to interactive processes
send_input(process_id, "y\n", "Confirming prompt")

🔒 Security Considerations

⚠️ Important Note

• This server provides direct Docker container access to MCP clients.
• The container has access to the host's ./tmp directory.
• Commands run with container - level permissions.
• Network access is enabled via host networking mode.

💡 Usage Tip

• Restrict Container Access: Limit which users can access the MCP server.
• Monitor File Operations: Regularly audit the ./tmp directory contents.
• Network Isolation: Consider using custom networks instead of host mode.
• Resource Limits: Add CPU and memory constraints to the container.
• Audit Logs: Monitor container command execution and file access.

🚨 Troubleshooting

Common Issues

Container won't start

# Check Docker is running
docker info

# Reset environment
./reset-docker.sh

Permission errors

# Ensure tmp directory is writable
chmod 755 ./tmp

MCP server connection issues

# Check server is running
npm run build && npm start

# Verify container is accessible
docker exec -it mcp-container echo "Hello"

Container name errors

# Check if your container exists
docker ps -a

# List all containers to find the correct name
docker ps --format "table {{.Names}}\t{{.Status}}"

# Start with correct container name
npm start -- --container-name your-actual-container-name

# The server will validate the container exists on startup

Multiple container setup

# Start additional containers with different names
docker run -d --name dev-container -v ./tmp:/app node:current-bookworm sleep infinity
docker run -d --name test-container -v ./tmp:/app node:current-bookworm sleep infinity

# Run MCP servers for each
npm run dev -- --container-name dev-container    # Terminal 1
npm run dev -- --container-name test-container   # Terminal 2

Process timeouts

• Adjust the maxWaitTime parameter in execute_command.
• Use check_process to monitor long - running operations.
• Consider breaking complex operations into smaller steps.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Make your changes.
4. Thoroughly test your changes in the container environment.
5. Commit your changes (git commit -m 'Add amazing feature').
6. Push to the branch (git push origin feature/amazing-feature).
7. Open a Pull Request.

Development Guidelines

• Adhere to TypeScript best practices.
• Incorporate comprehensive error handling.
• Include rationale parameters for all tool operations.
• Test with both quick and long - running commands.
• Document any new MCP tools or capabilities.

📦 Publishing to npm

Prerequisites

1. Create an npm account at npmjs.com.
2. Log in to npm: npm login.
3. Update package.json with your details:
   • author: Your name and email.
   • repository: Your GitHub repository URL.
   • homepage: Your project homepage.
   • bugs: Your issues URL.

Publishing Steps

# 1. Update version (patch/minor/major)
npm version patch

# 2. Build the project
npm run build

# 3. Test the package locally
npm pack
npm install -g ./docker-mcp-server-1.0.1.tgz

# 4. Test npx functionality
npx docker-mcp-server --help

# 5. Publish to npm
npm publish

# 6. Verify installation works
npx docker-mcp-server@latest --help

Post - Publishing

• Your package will be available at: https://www.npmjs.com/package/docker-mcp-server.
• Users can run it with: npx docker-mcp-server.
• Global installation: npm install -g docker-mcp-server.

📄 License

This project is licensed under the MIT License. For more details, refer to the LICENSE file.

🙋‍♂️ Support

• 🐛 Bug Reports: Please open an issue and provide detailed reproduction steps.
• 💡 Feature Requests: Open an issue, describing your use case and proposed solution.
• 📖 Documentation: Refer to the CLAUDE.md file for AI - assistant - specific guidance.
• 💬 Questions: Start a discussion for general questions and assistance.

Built for the Model Context Protocol ecosystem 🤖