Skip to main content
Glama
adamdude828

mcp-server-docker

by adamdude828
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

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

Related MCP server: MCP Docker Server

Installation

Via NPX (Recommended)

Run the MCP server directly without cloning:

npx mcp-server-docker

Or install globally:

npm install -g mcp-server-docker
mcp-server-docker

As a Docker Service

Add the following to your docker-compose.yml:

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

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

{
  "command": "string (required) - The command to execute",
  "service": "string (optional) - Docker service name"
}

Example Usage

{
  "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

# 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

Available Tools

1 tool
run_commandC

Execute a command inside a Docker container service

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe command to execute in the container
serviceNoDocker Compose service name (optional, uses default: laravel_app if not specified)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It does not disclose side effects, permissions, output format, or any warnings about executing arbitrary commands in a container. This is a significant gap for a potentially destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no fluff. It is front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite being a simple tool, running commands in a Docker container can have serious side effects. The description lacks any mention of return values, safety considerations, or operational context, and there is no output schema to fill the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both command and service documented. The description itself adds no extra parameter detail, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (execute a command) and the resource (Docker container service). It is a specific verb+resource pair, though it does not differentiate from siblings (none provided).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description merely states the action with no contextual direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • First observedrun_command
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The tool's purpose is clear and distinct from any non-existent others.

Naming Consistency5/5

The single tool name 'run_command' follows a clear verb_noun pattern. With only one tool, there are no inconsistencies to evaluate.

Tool Count2/5

The server is named for Docker but has only one tool, which is clearly too few for Docker-related operations. A single tool feels minimal and restricts the server's utility.

Completeness1/5

The tool surface is severely incomplete for a Docker server. It only supports running commands inside containers, with no tools for managing containers, images, networks, or volumes. This will cause agent failures in most Docker workflows.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Shell Command MCP Server

    kaznak
    A
    license
    A
    quality
    F
    maintenance
    Allows executing shell commands within a secure Docker container through Claude's MCP interface, providing Kubernetes tools and isolated environment without host Docker daemon access.
    2
    485
    5
    MIT

  • MCP Docker Server

    tenda-chi
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables secure Docker command execution from isolated environments like containers through MCP protocol. Provides tools for managing Docker containers, images, and Docker Compose services with security validation and async operation support.
    MIT

  • Docker MCP Server

    kenforthewin
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables secure execution of shell commands and file operations within isolated Docker containers. Provides process management, interactive input handling, and comprehensive file system operations for containerized development environments.
    186
    6
    MIT

  • Docker MCP

    Isak-Landin
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables remote Docker management over SSH via a local MCP server, providing tools to manage containers, images, Compose, and system resources.
    1
    GPL 3.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/adamdude828/mcp-server-docker'

If you have feedback or need assistance with the MCP directory API, please join our Discord server