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:

Cursor / Claude Code / Claude Desktop Configuration

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

Configuration:

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:

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):

Development

Development Scripts

Troubleshooting

Common Issues

1. Docker not running

Solution: Start Docker Desktop or the Docker daemon.

2. Docker permission denied

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

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

4. Container not found

Solution: Verify the container ID or name with list_containers.

5. Port already in use (HTTP mode)

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:

• Dockerode - Docker API client

• Model Context Protocol SDK - MCP implementation

• Zod - Schema validation

• Express - HTTP server