Docker MCP Server

A Model Context Protocol (MCP) server that runs entirely inside a Docker container, providing secure command execution and file operations through HTTP with bearer token authentication.

Features

• Containerized MCP Server: Runs entirely inside Docker with no host dependencies
• HTTP Transport: Network-based communication with bearer token authentication
• Secure Command Execution: Run shell commands in isolated container environment
• File Operations: Read, write, edit, and search files within container workspace
• 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

The MCP server runs inside a Docker container and communicates with clients over HTTP:

MCP Client (via HTTP)  Docker Container (Port 3000)
                              
                        MCP Server (Node.js)
                              
                    Workspace (/app/workspace)
                              
                    Host ./tmp directory (mounted)

Core Components

• Containerized MCP Server - TypeScript server using @modelcontextprotocol/sdk with StreamableHTTPServerTransport
• HTTP API - Network-based communication on port 3000
• Bearer Token Auth - Secure authentication for all requests
• Docker Container - Debian-based with Node.js, Playwright, and development tools
• Workspace Mount - Host ./tmp directory mounted to /app/workspace
• Process Tracking - Background process management with unique IDs

Key Differences from Traditional MCP Servers

• No Host Installation: Server runs entirely in container
• Network Access: HTTP-based instead of stdio transport
• Authentication Required: Bearer token for all requests
• Self-Contained: All dependencies bundled in container image
• Direct Execution: No docker exec overhead

Prerequisites

• Docker installed and running
• Docker Compose for container management
• Node.js (v18 or higher) for local development only

Quick Start

1. Clone and Setup

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

2. Start the Server

# Quick start: reset environment and start server
./reset-docker.sh

# Or manually:
npm run docker:build    # Build container with server code
npm run docker:up       # Start container
npm run docker:logs     # View logs and get auth token

3. Get Connection Info

The server logs display the authentication token and connection details:

npm run docker:logs

Look for output like:

============================================================
Docker MCP Server Starting
============================================================
Port: 3000
Auth Token: abc123-def456-ghi789
============================================================

4. Test Connection

# Test with curl
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     http://localhost:3000

# View server logs
npm run docker:logs

Development Commands

Docker Operations

# Build the container image with server code
npm run docker:build

# Start the containerized MCP server
npm run docker:up

# Stop the container
npm run docker:down

# View server logs (includes auth token)
npm run docker:logs

# Rebuild and restart (after code changes)
npm run docker:restart

# Open bash shell in container
npm run docker:shell

# Complete reset (clean workspace and rebuild)
./reset-docker.sh

Local Development

# Build TypeScript (for development/testing only)
npm run build

# Install/update dependencies
npm install

MCP Client Configuration

Configuration Format

MCP clients need to connect via HTTP with bearer token authentication:

{
  "url": "http://localhost:3000",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN_FROM_LOGS"
  }
}

Important:

• Get the auth token from container logs: npm run docker:logs
• Token is auto-generated on each container start
• Token must be included in the Authorization header with Bearer prefix

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": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_FROM_LOGS"
      }
    }
  }
}

Note: Replace YOUR_TOKEN_FROM_LOGS with the actual token from npm run docker:logs

Getting Your Authentication Token

1. Start the server: npm run docker:up
2. View logs: npm run docker:logs
3. Copy the token from the output
4. Update your client configuration with the token
5. Restart your MCP client

Verification

After configuration:

1. Restart your MCP client (e.g., Claude Desktop)
2. Check that the Docker MCP server shows as connected
3. Verify access to all available tools

Available MCP Tools

Command Execution

execute_command

Execute shell commands inside the container

Execute any shell command within the container environment with intelligent process tracking.

Parameters:

• command (string) - The shell command to execute
• rationale (string) - Explanation of why this command is being executed
• maxWaitTime (number, optional) - Maximum seconds to wait before returning (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 process…