convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
adamdude828

MCP Server Docker Command Runner

adamdude828/mcp-server-docker

Execute comandos em Docker containers diretamente do Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que permite executar comandos dentro de containers Docker via protocolo MCP. Funciona como um sidecar privilegiado integrado ao Claude, com suporte a timeouts configuráveis, captura de output em tempo real e allowlist de containers para segurança.

Instalação

$npx convez-ai adamdude828/mcp-server-docker

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 1 ano
Versão
—
Issues abertas
2
Contribuidores
3

Casos de uso

  • Executar testes automatizados dentro de containers durante desenvolvimento
  • Rodar scripts de deployment e CI/CD sem sair do Claude
  • Debugar aplicações em containers capturando logs e outputs em tempo real
  • Automação de tarefas DevOps dentro de ambientes containerizados

Veredito

Ferramenta sólida para integração Docker-MCP com foco em segurança via allowlist. Ideal para desenvolvedores que querem automação dentro do Claude sem expor todo o Docker socket, mas requer conhecimento de Docker Compose e gerenciamento adequado de permissões.

README

A tradução para o português deste README ainda está na fila.

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:

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
Ver o original no GitHub

Bom para

Relacionados