Registry / devops / mcp-server-docker

mcp-server-docker

library0.2.1jsnpmunverified

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.

devops ai-ml llm-agents

npm install mcp-server-docker

github ↗package ↗

INSTALL

IMPORT

SIG · MCP-SERVER-DOCKER

mcp-server-docker

devopsjavascriptv0.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DockerServer

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

✗ import DockerServer from 'mcp-server-docker'

Package exports a named class, not a default export.

runCommand

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

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

Package is ESM-only—no CommonJS support.

DockerConfig

✓ import type { DockerConfig } from 'mcp-server-docker'

✗ import { DockerConfig } from 'mcp-server-docker'

TypeScript type export, not a runtime value. Use `import type` to avoid runtime inclusion.

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); });

mcp-server-docker --version

Debug

Known issues

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

fix

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

affects: >=1.0.0

gotchaALLOWED_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.

affects: >=0.0.0

gotchaDefault command timeout is 300000 ms (5 minutes). Long-running commands may timeout.

fix

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

affects: >=0.0.0

deprecatedThe `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.

affects: >=0.5.0

Errors

Common errors & fixes

Error: "Service not found"

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: "Cannot connect to Docker daemon"

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: "Command timed out"

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.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

dockeroderequiredDocker engine API client used to execute commands in containers

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/adamdude828/mcp-server-docker ↗

packagehttps://www.npmjs.com/package/mcp-server-docker ↗