Docker 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 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 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 - `autoNewline` (boolean, optional) - Auto-add newline (default: true) ### 📁 File Operations All file operations work within `/app/workspace` which is mounted from host `./tmp`. #### `file_read` **Read files from container filesystem** Read file contents with support for large files through pagination. **Parameters:** - `filePath` (string) - Path relative to `/app/workspace` - `rationale` (string) - Explanation of why you need to read this file - `offset` (number, optional) - Starting line number (default: 0) - `limit` (number, optional) - Maximum lines to read (default: 2000) #### `file_write` **Create or overwrite files** Write content to files with automatic directory creation. **Parameters:** - `filePath` (string) - Path relative to `/app/workspace` - `content` (string) - The content to write - `rationale` (string) - Explanation of why you need to write this file **Important:** Use `file_read` first to understand current state. #### `file_edit` **Perform exact string replacements** Edit files using precise string matching with backup protection. **Parameters:** - `filePath` (string) - Path relative to `/app/workspace` - `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) - Replace all occurrences (default: false) **Important:** Use `file_read` first to get the exact text to match. #### `file_ls` **List directory contents** List files and directories with intelligent filtering. **Parameters:** - `path` (string, optional) - Directory path (default: current directory) - `rationale` (string) - Explanation of why you need to list this directory - `ignore` (array, optional) - Glob patterns to ignore #### `file_grep` **Search file contents** Search for patterns in files using grep with regex support. **Parameters:** - `pattern` (string) - Search pattern (supports regex) - `rationale` (string) - Explanation of why you need to search - `path` (string, optional) - Directory to search (default: current) - `include` (string, optional) - File pattern filter (e.g., '*.js') - `caseInsensitive` (boolean, optional) - Case insensitive (default: false) - `maxResults` (number, optional) - Result limit (default: 100) ## 📊 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, not fixed intervals ### Example Process Flow ```javascript // Long-running command gets backgrounded automatically const result1 = execute_command({ command: "npm install", rationale: "Installing dependencies" }); // Returns process ID if backgrounded // Check status later const result2 = check_process({ processId: result1.processId, rationale: "Checking installation progress" }); // Send input to interactive processes send_input({ processId: result1.processId, input: "y", rationale: "Confirming prompt" }); ``` ## 🔒 Security Considerations ### Authentication - **Bearer Token Required**: All requests must include valid bearer token - **Auto-Generated Token**: New token generated on each container start - **Token Rotation**: Restart container to generate new token - **CORS Enabled**: Allows cross-origin requests (consider restricting in production) ### Container Isolation - **Network Isolation**: Container exposed only on port 3000 - **Workspace Mount**: Only `./tmp` directory accessible from host - **User Permissions**: Commands run with container-level permissions - **No Host Access**: Server cannot access host filesystem outside mount ### Recommended Security Practices 1. **Token Management**: Keep authentication tokens secure and private 2. **Network Restrictions**: Use firewall rules to limit access to port 3000 3. **Workspace Isolation**: Regularly audit `./tmp` directory contents 4. **Resource Limits**: Add CPU and memory constraints in docker-compose.yml 5. **Access Logs**: Monitor container logs for suspicious activity ## 🚨 Troubleshooting ### Server Won't Start ```bash # Check Docker is running docker info # View container logs for errors npm run docker:logs # Verify port 3000 is available lsof -i :3000 # macOS/Linux netstat -ano | findstr :3000 # Windows # Complete reset npm run docker:down ./reset-docker.sh ``` ### Can't Connect to Server ```bash # Verify container is running docker ps | grep mcp-container # Check server logs for auth token npm run docker:logs # Ensure correct URL curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000 # Restart container npm run docker:restart ``` ### Code Changes Not Reflected ```bash # Remember: server code is built into container image # After changing TypeScript code, you MUST rebuild: npm run docker:restart # Or manually: npm run docker:down npm run docker:build npm run docker:up ``` ### Authentication Failed ```bash # Get current auth token from logs npm run docker:logs # Verify token format in client config # Must be: "Bearer YOUR_TOKEN" (with "Bearer " prefix) # Token changes on restart - update client config ``` ### Permission Errors in Workspace ```bash # Ensure tmp directory exists and is writable mkdir -p tmp chmod 755 tmp # Reset workspace rm -rf tmp && mkdir tmp ``` ### Process Timeout Issues - Increase `maxWaitTime` parameter in `execute_command` - Use `check_process` to monitor long-running operations - Break complex operations into smaller steps - Check container resources: `docker stats mcp-container` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes in `src/` 4. Test with `npm run docker:restart` 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 - Test authentication and security features ## 📦 Deployment ### Local Deployment ```bash # Production deployment docker-compose up -d # View production logs docker-compose logs -f mcp-container # Auto-restart on failure # (already configured with restart: unless-stopped) ``` ### Custom Configuration ```yaml # docker-compose.yml services: mcp-container: environment: - NODE_ENV=production - AUTH_TOKEN=your-custom-token # Optional: set custom token ports: - "3000:3000" # Change port mapping if needed volumes: - ./custom-workspace:/app/workspace ``` ### Environment Variables - `NODE_ENV`: Set to `production` for production deployment - Port: Configure via CLI flag `--port 3000` - Token: Set via CLI flag `--token your-token` (auto-generated if not set) ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙋‍♂️ Support - 🐛 **Bug Reports**: Open an issue with detailed reproduction steps - 💡 **Feature Requests**: Open an issue with your use case - 📖 **Documentation**: Check `CLAUDE.md` for AI assistant specific guidance - 💬 **Questions**: Open a discussion for general questions ## 📚 Additional Resources - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Docker Documentation](https://docs.docker.com/) --- **Built for the Model Context Protocol ecosystem** 🤖 **Features:** - ✅ HTTP Transport with Bearer Token Auth - ✅ Containerized Architecture - ✅ Process Management - ✅ File Operations - ✅ Network Accessible - ✅ Production Ready