container-exec-mcp

Container Exec MCP Server

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.

Table of Contents

• Container Exec MCP Server
  • Features
  • Table of Contents
  • Getting Started
    • Prerequisites
  • Configuration
    • Environment Variables
    • Cursor / Claude Code / Claude Desktop Configuration
    • HTTP Transport (for n8n or other HTTP clients)
  • Development
    • Development Scripts
  • Troubleshooting
    • Common Issues
    • Debug Logging
  • Contributing
  • License
  • Acknowledgments

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:

• Fork the repository
• Create a feature branch
• Make your changes
• Run npm run build to ensure it compiles
• Test your changes
• Submit a pull request

License

MIT

Acknowledgments

Built with:

• Dockerode - Docker API client
• Model Context Protocol SDK - MCP implementation
• Zod - Schema validation
• Express - HTTP server