mcp-server-docker 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# MCP Server: Docker Command Runner
+
+This MCP (Model Context Protocol) server provides a secure interface for running commands inside Docker containers. It acts as a privileged sidecar that can execute arbitrary commands within specified Docker Compose service containers.
+
+## Features
+
+- STDIO-based MCP transport for integration with Claude and other MCP clients
+- Execute commands in any Docker Compose service container
+- Real-time capture of stdout/stderr output
+- Secure container allowlist configuration
+- Configurable timeouts for long-running commands
+- Clear error messages for common Docker issues
+- Minimal dependencies and secure by design
+
+## Installation
+
+### Via NPX (Recommended)
+
+Run the MCP server directly without cloning:
+
+```bash
+npx mcp-server-docker
+```
+
+Or install globally:
+
+```bash
+npm install -g mcp-server-docker
+mcp-server-docker
+```
+
+### As a Docker Service
+
+Add the following to your `docker-compose.yml`:
+
+```yaml
+services:
+  mcp-docker:
+    build: ./mcp-server-docker
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    ports:
+      - "3001:3000"  # Expose MCP server
+    environment:
+      - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}
+      - DEFAULT_SERVICE=app
+      - COMPOSE_FILE=docker-compose.yml
+      - PORT=3000
+    networks:
+      - your-network
+```
+
+### For Local Development
+
+```bash
+cd mcp-server-docker
+npm install
+npm run build
+```
+
+## Configuration
+
+The server accepts the following environment variables:
+
+- `ALLOWED_CONTAINERS`: Comma-separated list of allowed service:container pairs (e.g., "app:myapp_container,db:mydb_container")
+- `DEFAULT_SERVICE`: Default service to run commands in (default: "laravel_app")
+- `COMMAND_TIMEOUT`: Command timeout in milliseconds (default: 300000)
+
+## MCP Tool: run_command
+
+The server exposes a single tool called `run_command`:
+
+### Input Schema
+
+```json
+{
+  "command": "string (required) - The command to execute",
+  "service": "string (optional) - Docker service name"
+}
+```
+
+### Example Usage
+
+```json
+{
+  "command": "npm test",
+  "service": "frontend"
+}
+```
+
+### Response Format
+
+The tool returns the command output with the following structure:
+- Standard output (if any)
+- Standard error (if any, prefixed with [stderr])
+- Exit code
+
+## Usage
+
+The server uses STDIO transport for MCP communication. When run with `npx mcp-server-docker`, it will:
+
+1. Parse environment variables for allowed containers
+2. Start the MCP server listening on stdin/stdout
+3. Log startup information to stderr
+4. Wait for MCP protocol messages
+
+## Security Notes
+
+- This server requires access to the Docker socket - ensure Docker is running and accessible
+- No command filtering is applied - relies on container isolation for security
+- Commands timeout after 5 minutes by default
+- Only allowed containers (configured via ALLOWED_CONTAINERS) can be accessed
+
+## Development
+
+```bash
+# Run in development mode
+npm run dev
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+```
+
+## Troubleshooting
+
+### Common Errors
+
+1. **"Cannot connect to Docker daemon"**: Ensure Docker is running and the socket is mounted
+2. **"Service not found"**: Check that the service name exists in your docker-compose.yml
+3. **"Command timed out"**: Command exceeded 5-minute timeout, consider breaking it into smaller operations

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
+import * as dotenv from "dotenv";
+dotenv.config();
+// Parse allowed containers from environment variable
+// Format: "service1:container1,service2:container2"
+function parseAllowedContainers() {
+    const allowedStr = process.env.ALLOWED_CONTAINERS || "";
+    const containers = {};
+    if (allowedStr) {
+        const pairs = allowedStr.split(',');
+        for (const pair of pairs) {
+            const [service, container] = pair.split(':');
+            if (service && container) {
+                containers[service.trim()] = container.trim();
+            }
+        }
+    }
+    // Return default if no containers specified
+    if (Object.keys(containers).length === 0) {
+        console.error("Warning: No allowed containers specified in ALLOWED_CONTAINERS environment variable");
+        return {
+            "laravel_app": "laravel_app_dev"
+        };
+    }
+    return containers;
+}
+const ALLOWED_CONTAINERS = parseAllowedContainers();
+const DEFAULT_TIMEOUT = parseInt(process.env.COMMAND_TIMEOUT || "300000");
+const DEFAULT_SERVICE = process.env.DEFAULT_SERVICE || "laravel_app";
+async function runDockerCommand(command, service) {
+    const targetService = service || DEFAULT_SERVICE;
+    // Check if the service is allowed
+    if (!ALLOWED_CONTAINERS[targetService]) {
+        throw new Error(`Service '${targetService}' is not allowed. Allowed services: ${Object.keys(ALLOWED_CONTAINERS).join(', ')}`);
+    }
+    const containerName = ALLOWED_CONTAINERS[targetService];
+    // Build docker exec command
+    const dockerArgs = ["exec", containerName, "sh", "-c", command];
+    return new Promise((resolve, reject) => {
+        // Use docker directly
+        const dockerProcess = spawn("docker", dockerArgs);
+        let stdout = "";
+        let stderr = "";
+        // Set timeout
+        const timeout = setTimeout(() => {
+            dockerProcess.kill();
+            reject(new Error(`Command timed out after ${DEFAULT_TIMEOUT}ms`));
+        }, DEFAULT_TIMEOUT);
+        dockerProcess.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        dockerProcess.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        dockerProcess.on("close", (code) => {
+            clearTimeout(timeout);
+            resolve({
+                stdout,
+                stderr,
+                exitCode: code || 0,
+            });
+        });
+        dockerProcess.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+// Create server instance
+const server = new Server({
+    name: "mcp-server-docker",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handler for listing available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "run_command",
+                description: "Execute a command inside a Docker container service",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        command: {
+                            type: "string",
+                            description: "The command to execute in the container",
+                        },
+                        service: {
+                            type: "string",
+                            description: `Docker Compose service name (optional, uses default: ${DEFAULT_SERVICE} if not specified)`,
+                        },
+                    },
+                    required: ["command"],
+                },
+            },
+        ],
+    };
+});
+// Handler for tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "run_command") {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    const { command, service } = request.params.arguments;
+    if (!command) {
+        throw new Error("Command is required");
+    }
+    try {
+        const result = await runDockerCommand(command, service);
+        // Format the response
+        let response = "";
+        if (result.stdout) {
+            response += result.stdout;
+        }
+        if (result.stderr) {
+            if (response)
+                response += "\n\n";
+            response += `[stderr]\n${result.stderr}`;
+        }
+        response += `\n\nExit code: ${result.exitCode}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: response,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide helpful error messages for common issues
+        if (errorMessage.includes("No such service")) {
+            throw new Error(`Service '${service || DEFAULT_SERVICE}' not found. Available services can be listed with 'docker compose ps'.`);
+        }
+        else if (errorMessage.includes("Cannot connect to the Docker daemon")) {
+            throw new Error("Cannot connect to Docker daemon. Ensure Docker is running and the socket is mounted.");
+        }
+        else if (errorMessage.includes("timed out")) {
+            throw new Error(`Command timed out after ${DEFAULT_TIMEOUT / 1000} seconds. Consider running shorter commands or increasing the timeout.`);
+        }
+        throw new Error(`Failed to execute command: ${errorMessage}`);
+    }
+});
+// Start the server using stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Server Docker started");
+    console.error(`Default service: ${DEFAULT_SERVICE}`);
+    console.error(`Allowed containers: ${Object.keys(ALLOWED_CONTAINERS).join(', ')}`);
+}
+main().catch((error) => {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/mcp-config.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "docker-runner": {
+      "url": "http://localhost:3000",
+      "transport": "sse",
+      "description": "MCP server for executing commands in Docker containers"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mcp-server-docker",
+  "version": "1.0.0",
+  "description": "MCP server for executing commands in Docker containers",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-server-docker": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/**/*",
+    "mcp-config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["mcp", "docker", "model-context-protocol", "cli", "container"],
+  "author": "adamdude828",
+  "homepage": "https://github.com/adamdude828/mcp-server-docker#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamdude828/mcp-server-docker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adamdude828/mcp-server-docker/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.18.2",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/express": "^4.17.21",
+    "@types/uuid": "^9.0.7",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.11"
+  }
+}