# docker-mcp-server
## 基本信息
- Slug: `kenforthewin-docker-mcp-server`
- Source: modelscope
- Publisher: @kenforthewin/docker-mcp-server
- Categories: shell-access / file-systems / virtualization
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@kenforthewin/docker-mcp-server
## 简介
暂无描述。
## 安装提示

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

## MCP Server 详情

# 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](https://www.docker.com/get-started) installed and running
- [Docker Compose](https://docs.docker.com/compose/install/) for container management
- [Node.js](https://nodejs.org/) (v18 or higher) for local development only

##  Quick Start

### 1. Clone and Setup

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

### 2. Start the Server

```bash
# 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:

```bash
npm run docker:logs
```

Look for output like:
```
============================================================
Docker MCP Server Starting
============================================================
Port: 3000
Auth Token: abc123-def456-ghi789
============================================================
```

### 4. Test Connection

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

# View server logs
npm run docker:logs
```

##  Development Commands

### Docker Operations

```bash
# 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

```bash
# 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:

```json
{
  "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:**
```json
{
  "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…