Docker MCP Server

Docker MCP Server

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

🚀 Features

• Secure Command Execution: Run shell commands in isolated Docker containers
• File Operations: Read, write, edit, and search files within containers
• Process Management: Track long-running processes with unique IDs
• Interactive Input: Send input to running processes
• Smart Timeouts: Intelligent process timeout handling based on output activity

🏗️ Architecture

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

Core Components

• MCP Server (src/index.ts) - TypeScript server using @modelcontextprotocol/sdk
• Docker Container - Debian-based container with Node.js and development tools
• File Mount - Host ./tmp directory mounted to container /app for persistence
• Process Tracking - Background process management with unique IDs and monitoring

📋 Prerequisites

• Docker installed and running
• Docker Compose for easy container management
• Node.js (v18 or higher) for the MCP server
• npm for dependency management

🚀 Quick Start

Option 1: Run with npx (Recommended)

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

Option 2: Install Globally

Option 3: Development Setup

1. Clone and Setup

2. Start the Environment

This script will:

• Stop any existing containers
• Clean the /tmp directory
• Start the container in the background
• Drop you into an interactive shell

3. Build and Run the MCP Server

🔧 CLI Usage

The MCP server supports the following command-line options:

Container Name Configuration

You can configure the Docker container name in several ways:

1. Default: Uses mcp-container if no option is provided
2. CLI Argument: --container-name or -c flag
3. Multiple Instances: Run multiple MCP servers with different containers

⚙️ 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:

With custom container:

Other MCP Clients

For other MCP clients, use the following command:

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 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 the available tools for container-based development.

🛠️ Development Commands

Container Management

Build and Run

🔧 Available MCP Tools

The server provides 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 with intelligent process tracking and timeout handling.

Parameters:

• command (string) - The shell command to execute in the container
• rationale (string) - Explanation of why this command is being executed
• maxWaitTime (number, optional) - Maximum seconds to wait before returning to agent (default: 20)

Features:

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

check_process

Monitor background processes by ID

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

Parameters:

• processId (string) - The process ID returned by a long-running command
• rationale (string) - 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 that are waiting for user input.

Parameters:

• processId (string) - The process ID of the running process
• input (string) - The input to send to the process
• rationale (string) - 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 read (relative to /app in container)
• rationale (string) - Explanation of why you need to read this file
• offset (number, optional) - Starting line number (0-based, default: 0)
• limit (number, optional) - 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 write (relative to /app in container)
• content (string) - The content to write to the file
• rationale (string) - 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 edit (relative to /app in container)
• oldString (string) - The exact text to replace
• newString (string) - The replacement text
• rationale (string) - 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 get 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) - Explanation of why you need to list this directory
• ignore (array of strings, optional) - 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) - Explanation of why you need to search for this pattern
• path (string, optional) - The directory to search in (default: current directory)
• include (string, optional) - File pattern to include (e.g., '.js', '.{ts,tsx}')
• caseInsensitive (boolean, optional) - Case insensitive search (default: false)
• maxResults (number, optional) - 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 run with intelligent timeout handling:

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

Example Process Flow

🔒 Security Considerations

⚠️ Important Security Notes:

• 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

Recommended Security Practices

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

🚨 Troubleshooting

Common Issues

Container won't start:

Permission errors:

MCP server connection issues:

Container name errors:

Multiple container setup:

Process timeouts:

• Adjust 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. Test thoroughly with 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

• Follow TypeScript best practices
• Add 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

To publish this package to npm for global use:

Prerequisites

1. Create an npm account at npmjs.com
2. Login 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

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 - see the LICENSE file for details.

🙋‍♂️ Support

• 🐛 Bug Reports: Please open an issue with detailed reproduction steps
• 💡 Feature Requests: Open an issue with your use case and proposed solution
• 📖 Documentation: Check the CLAUDE.md file for AI assistant specific guidance
• 💬 Questions: Open a discussion for general questions and help

Built for the Model Context Protocol ecosystem 🤖