Docker Command Runner MCP Server

1.0.0 verified Sat Apr 25 auth: no javascript

MCP server (v1.0.0) that executes commands inside Docker containers via Model Context Protocol. Provides a single `run_command` tool for running arbitrary commands in allowed Docker Compose service containers. Uses STDIO transport, supports container allowlisting via environment variables, configurable timeouts, and captures stdout/stderr. Minimal dependencies, ships TypeScript types. Released under MIT license. Key differentiator: purpose-built for MCP (Claude) integration rather than generic Docker exec wrappers. Requires Docker socket access and security relies on container isolation.

Common errors

error Error: "Service not found" ↓

cause The service name provided does not match any service defined in docker-compose.yml.

fix

Verify the service name exists in your docker-compose.yml and that the Docker Compose project is running. Use docker-compose ps to list services.

error Error: "Cannot connect to Docker daemon" ↓

cause The Docker socket (/var/run/docker.sock) is not accessible or Docker is not running.

fix

Ensure Docker is installed and running. If using a remote host, set DOCKER_HOST environment variable or mount the socket volume (e.g., -v /var/run/docker.sock:/var/run/docker.sock).

error Error: "Command timed out" ↓

cause The command ran longer than the configured timeout (default 5 minutes).

fix

Increase COMMAND_TIMEOUT environment variable or commandTimeout in config. Alternatively, break the command into smaller parts.

Warnings

breaking v1.0.0 removed support for STDIO transport as default; must now explicitly use start() method. ↓

fix Replace direct instantiation with `new DockerServer(config).start()`.

gotcha ALLOWED_CONTAINERS must be a comma-separated list of 'service:container' pairs. If misconfigured, no containers will be allowed. ↓

fix Set environment variable like `ALLOWED_CONTAINERS=web:web-1,worker:celery-1` or pass array to constructor. Do not use spaces.

gotcha Default command timeout is 300000 ms (5 minutes). Long-running commands may timeout. ↓

fix Set COMMAND_TIMEOUT environment variable or pass commandTimeout in config (milliseconds).

deprecated The `DEFAULT_SERVICE` environment variable is deprecated in favor of using the `defaultService` option in constructor. ↓

fix Pass `defaultService` in constructor config object instead of relying on environment variable.

Install

npm install mcp-server-docker

yarn add mcp-server-docker

pnpm add mcp-server-docker

Imports

DockerServer

wrong

import DockerServer from 'mcp-server-docker'

correct

import { DockerServer } from 'mcp-server-docker'

Package exports a named class, not a default export.

runCommand

wrong

const { runCommand } = require('mcp-server-docker')

correct

import { runCommand } from 'mcp-server-docker'

Package is ESM-only—no CommonJS support.

DockerConfig
wrong
```
import { DockerConfig } from 'mcp-server-docker'
```
correct
```
import type { DockerConfig } from 'mcp-server-docker'
```
TypeScript type export, not a runtime value. Use `import type` to avoid runtime inclusion.

Quickstart

Initialize and start the Docker MCP server using environment variables for configuration.

import { DockerServer } from 'mcp-server-docker';

const server = new DockerServer({
  allowedContainers: process.env.ALLOWED_CONTAINERS?.split(',') ?? [
    'app:app_container',
  ],
  defaultService: process.env.DEFAULT_SERVICE ?? 'laravel_app',
  commandTimeout: parseInt(process.env.COMMAND_TIMEOUT ?? '300000', 10),
});

server.start().catch((err: Error) => {
  console.error('Failed to start server:', err);
  process.exit(1);
});