Skip to main content
Glama
Container Exec MCP Server

Container Exec MCP Server

by davidkim9

Container Exec MCP Server

Let it run code

A Model Context Protocol (MCP) server that provides Docker container automation capabilities. This server enables AI assistants like Claude/Cursor/ChatGPT to manage and interact with Docker containers, execute commands, and inspect container information.

This package minimizes the amount of tools to help AI Agents pick the right tool for a given prompt.

Features

  • 🐳 Container Management - List and inspect Docker containers

  • 🔧 Command Execution - Execute commands inside containers

  • 📊 Detailed Information - Get comprehensive container details

  • 🚀 Dual Transport - HTTP and stdio (for Claude Code/Cursor)

For detailed information about available tools, see tools.md.

Related MCP server: Docker MCP Server

Table of Contents

Getting Started

Prerequisites

  • Node.js 18 or higher

  • Docker installed and running

  • npm or yarn

Configuration

Environment Variables

Configure the server behavior using environment variables:

Variable

Description

Default

Options

PORT

HTTP server port

4200

Any valid port number

MCP_AUTH_TOKEN

Authentication token for HTTP server (optional)

None

Any string

Cursor / Claude Code / Claude Desktop Configuration

To use this server with Cursor/Claude Code/Claude Desktop, add it to your MCP settings file.

Configuration:

{
  "mcpServers": {
    "container-exec": {
      "command": "npx",
      "args": [
        "container-exec-mcp"
      ]
    }
  }
}

Note: After updating the configuration, restart Claude Code/Desktop for changes to take effect.

Important: Ensure Docker is running and accessible on your system.

HTTP Transport (for n8n or other HTTP clients)

Start the HTTP server:

npm install
npm start
# or with custom port
PORT=4200 npm start

# With authentication (recommended)
MCP_AUTH_TOKEN=your-secret-token npm start

The server will listen on http://localhost:4200/mcp (or your custom port).

Authentication (Optional):

You can secure the HTTP server with token-based authentication by setting the MCP_AUTH_TOKEN environment variable. If set, all requests must include the token in the Authorization header.

Example HTTP Request (with authentication):

curl -X POST http://localhost:4200/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_containers",
      "arguments": {
        "all": true
      }
    }
  }'

Development

Development Scripts

npm install

# Start HTTP server with auto-reload
npm run dev

# Start stdio server with auto-reload
npm run dev:stdio

# Build TypeScript to JavaScript
npm run build

Troubleshooting

Common Issues

1. Docker not running

Error: connect ENOENT /var/run/docker.sock

Solution: Start Docker Desktop or the Docker daemon.

2. Docker permission denied

Error: permission denied while trying to connect to the Docker daemon socket

Solution: On Linux, add your user to the docker group: sudo usermod -aG docker $USER (then log out and back in).

3. Node.js version too old

Error: Node.js 18 or higher required

Solution: Update Node.js to version 18 or higher.

4. Container not found

Error: No such container: xyz

Solution: Verify the container ID or name with list_containers.

5. Port already in use (HTTP mode)

Error: listen EADDRINUSE: address already in use :::4200

Solution: Change the port with PORT=3001 npm start

Debug Logging

For stdio mode, logs are written to stderr and appear in Claude Code logs:

  • macOS: ~/Library/Logs/Claude/mcp-server-container-exec-mcp.log

  • Linux: ~/.config/Claude/logs/mcp-server-container-exec-mcp.log

For HTTP mode, logs appear in the terminal where you started the server.

Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run npm run build to ensure it compiles

  5. Test your changes

  6. Submit a pull request

License

MIT

Acknowledgments

Built with:

Available Tools

3 tools
execC

Execute a command in a Docker container

Inputs: container_id (required), command (required), stdin, working_dir, +3 more.

get_container_infoA

Get detailed information about a specific Docker container including state, network, mounts, environment, and resource configuration.

Inputs: container_id (required).

list_containersA

List Docker containers. By default shows only running containers, use all=true to show all containers including stopped ones.

Inputs: all.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: exec for command execution, get_container_info for detailed container metadata, and list_containers for container enumeration. There is no overlap in functionality, making tool selection straightforward for an agent.

    Naming Consistency4/5

    Two tools follow a consistent verb_noun pattern (get_container_info, list_containers), but exec uses a standalone verb without a noun. While the naming is readable and mostly consistent, the deviation from the pattern slightly reduces predictability.

    Tool Count4/5

    Three tools are reasonable for a Docker container management server, covering core operations like listing, inspecting, and executing commands. However, the scope feels slightly thin, as common operations like starting/stopping containers or managing images are missing, though not critically so.

    Completeness3/5

    The toolset covers basic read and execute operations (list, get, exec) but lacks lifecycle management tools such as start, stop, create, or delete containers. This creates notable gaps that agents may need to work around, limiting full container management workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants like Claude to manage Docker containers, images, and Docker Compose deployments through the Model Context Protocol. Provides secure container lifecycle management, image operations, and multi-host Docker server connections.
      1,176 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Docker containers through safe, permission-controlled access to inspect, manage, and diagnose containers, images, and compose services with built-in timeouts and AI-powered analysis.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Docker containers, images, networks, volumes, and Compose services through the Model Context Protocol. It supports system operations, command execution within containers, and integration with Docker Hub and GitHub Container Registry.
      167 npm
      2
      MIT