{
  "markdown": "# Docker MCP Server\n\n<div align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/alisaitteke/docker-mcp/develop/social_preview.png\" alt=\"Docker MCP Server\" width=\"600\"/>\n</div>\n\n<div align=\"center\">\n\n**Powerful Docker management for AI assistants**\n\n[![npm version](https://img.shields.io/npm/v/@alisaitteke/docker-mcp.svg)](https://www.npmjs.com/package/@alisaitteke/docker-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n\n</div>\n\nA comprehensive Model Context Protocol (MCP) server that empowers AI assistants like Cursor, Claude Desktop, and other MCP-compatible clients to seamlessly manage Docker containers, images, networks, volumes, and registries through natural language interactions.\n\n## Why Docker MCP Server?\n\n- **Zero Configuration** - Works out of the box with `npx`, no installation needed\n- **Safety First** - Two-step confirmation for destructive operations\n- **Cross-Platform** - Works on Windows, Linux, and macOS with automatic Docker socket detection\n- **Comprehensive** - Full Docker API coverage including Compose, registries, and system operations\n- **AI-Native** - Designed specifically for AI assistants with clear, structured responses\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/star-white.svg\"><img src=\"docs/icons/star.svg\" width=\"24\" height=\"24\" alt=\"Features\"></picture> Features\n\n### Container Management\n- **Full lifecycle control**: Create, start, stop, restart, kill, and remove containers\n- **Monitoring**: Real-time logs, statistics, and container inspection\n- **Advanced operations**: Pause/unpause, exec commands, and resource management\n\n### Image Management\n- **Registry operations**: Pull, push, tag, and remove images\n- **Build support**: Build images from Dockerfiles with full configuration\n- **Inspection**: Detailed image history, layers, and metadata\n\n### Network Management\n- **Network operations**: Create, remove, and inspect Docker networks\n- **Container connectivity**: Connect/disconnect containers from networks\n- **Network discovery**: List and filter networks with advanced options\n\n### Volume Management\n- **Volume operations**: Create, remove, and inspect volumes\n- **Data persistence**: Manage persistent storage for containers\n- **Volume inspection**: Detailed volume information and mount points\n\n### System Operations\n- **System information**: Docker daemon info, version, and capabilities\n- **Resource cleanup**: Prune unused images, containers, volumes, and networks\n- **Event monitoring**: Real-time Docker event stream\n\n### Container Execution\n- **Command execution**: Run commands in running containers\n- **Interactive sessions**: Create and manage exec instances\n- **Output streaming**: Real-time command output and logs\n\n### Registry Integration\n- **Docker Hub**: Search repositories, list tags, authenticate, pull/push images\n- **GitHub Container Registry (GHCR)**: Full authentication and image management\n- **Multi-registry support**: Seamlessly work with multiple registries\n\n### Docker Compose Support\n- **Multi-container management**: Start, stop, restart compose services\n- **Service monitoring**: View logs and status of compose services\n- **Build operations**: Build compose services with dependency management\n- **Configuration validation**: Parse and validate docker-compose.yml files\n\n### Safety Features\n- **Two-step confirmation** for all destructive operations\n- **Resource preview**: See what will be deleted before confirmation\n- **Dual confirmation methods**:\n  - **Confirm parameter** (default): Works everywhere, simple and reliable\n  - **MCP Elicitation API** (advanced): Interactive form-based confirmation for better UX\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/package-white.svg\"><img src=\"docs/icons/package.svg\" width=\"24\" height=\"24\" alt=\"Installation\"></picture> Installation\n\n### Via npx (Recommended)\n\n```bash\nnpx @alisaitteke/docker-mcp\n```\n\n### Local Installation\n\n```bash\nnpm install -g @alisaitteke/docker-mcp\n```\n\nOr install locally in your project:\n\n```bash\nnpm install @alisaitteke/docker-mcp\n```\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/rocket-white.svg\"><img src=\"docs/icons/rocket.svg\" width=\"24\" height=\"24\" alt=\"Quick Start\"></picture> Quick Start\n\n### With Cursor\n\n1. Add to your Cursor MCP configuration (usually in `.cursor/mcp.json` or similar):\n\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"npx\",\n      \"args\": [\"@alisaitteke/docker-mcp\"]\n    }\n  }\n}\n```\n\n2. Restart Cursor and start managing Docker with AI!\n\n### With Claude Desktop\n\n1. Add to your Claude Desktop configuration:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"npx\",\n      \"args\": [\"@alisaitteke/docker-mcp\"]\n    }\n  }\n}\n```\n\n2. Restart Claude Desktop and start managing Docker with AI!\n\n## Local Development and Testing\n\n### Prerequisites\n\n- Node.js 18.0.0 or higher\n- Docker daemon running\n- npm or yarn\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd docker-mcp\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the project:\n```bash\nnpm run build\n```\n\n### Running Locally\n\n#### Method 1: Using npm start (after build)\n\n```bash\n# Build first\nnpm run build\n\n# Run the server\nnpm start\n```\n\n#### Method 2: Using npm run dev (development mode with tsx)\n\n```bash\nnpm run dev\n```\n\nThis uses `tsx` to run TypeScript directly without building.\n\n#### Method 3: Direct execution\n\n```bash\n# Build first\nnpm run build\n\n# Run directly with node\nnode dist/index.js\n```\n\n#### Method 4: Using the binary\n\n```bash\n# Build first\nnpm run build\n\n# Make sure the binary is executable\nchmod +x bin/docker-mcp-server.js\n\n# Run the binary\n./bin/docker-mcp-server.js\n```\n\n### Development Workflow\n\n1. Make changes to source files in `src/`\n2. Build the project:\n```bash\nnpm run build\n```\n3. Test the changes:\n```bash\nnpm start\n# or\nnpm run dev\n```\n4. Check for TypeScript errors:\n```bash\nnpm run typecheck\n```\n5. Lint the code:\n```bash\nnpm run lint\n```\n\n### Troubleshooting\n\n**Docker connection issues:**\n- Ensure Docker daemon is running: `docker ps`\n- **Linux/macOS**: Check Docker socket permissions: `ls -la /var/run/docker.sock`\n- **Windows**: Ensure Docker Desktop is running and named pipe is accessible\n- For remote Docker, set environment variables: `DOCKER_HOST`, `DOCKER_CERT_PATH`, etc.\n- **macOS**: If `/var/run/docker.sock` doesn't exist, try `~/.docker/run/docker.sock` (Docker Desktop 4.0+)\n\n**Build errors:**\n- Clear node_modules and reinstall: `rm -rf node_modules && npm install`\n- Check TypeScript version compatibility\n- Ensure all dependencies are installed: `npm install`\n\n**Runtime errors:**\n- Check that Docker is accessible: `docker version`\n- Verify the build was successful: `ls -la dist/`\n- Check server logs (errors are written to stderr)\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/gear-white.svg\"><img src=\"docs/icons/gear.svg\" width=\"24\" height=\"24\" alt=\"Configuration\"></picture> Configuration\n\nThe server automatically detects the operating system and uses the appropriate Docker socket path:\n\n### Platform-Specific Defaults\n\n- **Linux**: `/var/run/docker.sock` (Unix socket)\n- **macOS**: `/var/run/docker.sock` or `~/.docker/run/docker.sock` (Docker Desktop 4.0+)\n- **Windows**: `//./pipe/docker_engine` (Named pipe)\n\n### Connection Methods (in order of priority)\n\n1. **Environment variables** (highest priority):\n   - `DOCKER_HOST` - Docker daemon host (e.g., `tcp://localhost:2376`, `npipe:////./pipe/docker_engine`)\n   - `DOCKER_PORT` - Docker daemon port\n   - `DOCKER_PROTOCOL` - Protocol (`http` or `https`)\n   - `DOCKER_SOCKET_PATH` - Path to Docker socket (overrides platform default)\n   - `DOCKER_CERT_PATH` - Path to Docker certificates directory\n   - `DOCKER_TLS_VERIFY` - Enable TLS verification (`1` or `0`)\n\n2. **Platform-specific defaults** (automatic detection):\n   - Linux: `/var/run/docker.sock`\n   - macOS: `/var/run/docker.sock` (or `~/.docker/run/docker.sock` if available)\n   - Windows: `//./pipe/docker_engine`\n\n### Windows Configuration\n\nOn Windows, Docker Desktop uses named pipes. The server automatically detects Windows and uses the correct path. You can also explicitly set:\n\n```bash\n# Using environment variable\nset DOCKER_SOCKET_PATH=//./pipe/docker_engine\n\n# Or using DOCKER_HOST\nset DOCKER_HOST=npipe:////./pipe/docker_engine\n```\n\n### Remote Docker Host\n\nTo connect to a remote Docker host:\n\n```bash\n# Linux/macOS\nexport DOCKER_HOST=tcp://192.168.1.100:2376\nexport DOCKER_TLS_VERIFY=1\nexport DOCKER_CERT_PATH=/path/to/certs\n\n# Windows\nset DOCKER_HOST=tcp://192.168.1.100:2376\nset DOCKER_TLS_VERIFY=1\nset DOCKER_CERT_PATH=C:\\path\\to\\certs\n```\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/wrench-white.svg\"><img src=\"docs/icons/wrench.svg\" width=\"24\" height=\"24\" alt=\"Available Tools\"></picture> Available Tools\n\n### Container Tools\n- `docker_list_containers` - List all containers\n- `docker_create_container` - Create a new container\n- `docker_start_container` - Start a container\n- `docker_stop_container` - Stop a container\n- `docker_restart_container` - Restart a container\n- `docker_kill_container` - Kill a container\n- `docker_remove_container` - Remove a container\n- `docker_inspect_container` - Get container details\n- `docker_container_logs` - Get container logs\n- `docker_container_stats` - Get container statistics\n- `docker_pause_container` - Pause a container\n- `docker_unpause_container` - Unpause a container\n\n### Image Tools\n- `docker_list_images` - List all images\n- `docker_pull_image` - Pull an image from registry\n- `docker_push_image` - Push an image to registry\n- `docker_tag_image` - Tag an image\n- `docker_remove_image` - Remove an image\n- `docker_inspect_image` - Get image details\n- `docker_image_history` - Get image history\n\n### Network Tools\n- `docker_list_networks` - List all networks\n- `docker_create_network` - Create a network\n- `docker_remove_network` - Remove a network\n- `docker_inspect_network` - Get network details\n- `docker_connect_container` - Connect container to network\n- `docker_disconnect_container` - Disconnect container from network\n\n### Volume Tools\n- `docker_list_volumes` - List all volumes\n- `docker_create_volume` - Create a volume\n- `docker_remove_volume` - Remove a volume\n- `docker_inspect_volume` - Get volume details\n\n### System Tools\n- `docker_system_info` - Get Docker system information\n- `docker_version` - Get Docker version\n- `docker_prune_system` - Prune all unused resources\n- `docker_prune_images` - Prune unused images\n- `docker_prune_containers` - Prune stopped containers\n- `docker_prune_volumes` - Prune unused volumes\n- `docker_prune_networks` - Prune unused networks\n\n### Exec Tools\n- `docker_exec` - Execute a command in a container\n- `docker_inspect_exec` - Get exec instance details\n\n### Compose Tools\n- `docker_compose_up` - Start Docker Compose services\n- `docker_compose_down` - Stop and remove Docker Compose services\n- `docker_compose_ps` - List Docker Compose services\n- `docker_compose_logs` - View output from Docker Compose services\n- `docker_compose_config` - Parse and validate docker-compose.yml file\n- `docker_compose_build` - Build Docker Compose services\n- `docker_compose_restart` - Restart Docker Compose services\n- `docker_compose_stop` - Stop Docker Compose services\n- `docker_compose_start` - Start Docker Compose services\n\n### Registry Tools\n- `dockerhub_search` - Search Docker Hub\n- `dockerhub_get_tags` - Get repository tags from Docker Hub\n- `dockerhub_authenticate` - Authenticate with Docker Hub\n- `dockerhub_pull` - Pull from Docker Hub\n- `dockerhub_push` - Push to Docker Hub\n- `ghcr_authenticate` - Authenticate with GitHub Container Registry\n- `ghcr_pull` - Pull from GHCR\n- `ghcr_push` - Push to GHCR\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/document-white.svg\"><img src=\"docs/icons/document.svg\" width=\"24\" height=\"24\" alt=\"Examples\"></picture> Examples\n\n### List running containers\n```json\n{\n  \"name\": \"docker_list_containers\",\n  \"arguments\": {\n    \"all\": false\n  }\n}\n```\n\n### Create and start a container\n```json\n{\n  \"name\": \"docker_create_container\",\n  \"arguments\": {\n    \"image\": \"nginx:latest\",\n    \"name\": \"my-nginx\",\n    \"ports\": {\"80/tcp\": {}}\n  }\n}\n```\n\nThen start it:\n```json\n{\n  \"name\": \"docker_start_container\",\n  \"arguments\": {\n    \"id\": \"my-nginx\"\n  }\n}\n```\n\n### Pull an image from Docker Hub\n```json\n{\n  \"name\": \"docker_pull_image\",\n  \"arguments\": {\n    \"name\": \"ubuntu:20.04\"\n  }\n}\n```\n\n### Search Docker Hub\n```json\n{\n  \"name\": \"dockerhub_search\",\n  \"arguments\": {\n    \"query\": \"node\",\n    \"limit\": 10\n  }\n}\n```\n\n### Execute a command in a container\n```json\n{\n  \"name\": \"docker_exec\",\n  \"arguments\": {\n    \"containerId\": \"my-container\",\n    \"cmd\": [\"ls\", \"-la\"],\n    \"tty\": false\n  }\n}\n```\n\n### Start Docker Compose services\n```json\n{\n  \"name\": \"docker_compose_up\",\n  \"arguments\": {\n    \"projectDir\": \"/path/to/compose/project\",\n    \"detach\": true,\n    \"build\": true\n  }\n}\n```\n\n### View Compose logs\n```json\n{\n  \"name\": \"docker_compose_logs\",\n  \"arguments\": {\n    \"projectDir\": \"/path/to/compose/project\",\n    \"follow\": false,\n    \"tail\": 100\n  }\n}\n```\n\n### Removing Resources with Confirmation\n\nAll destructive operations (remove, kill, prune) support two confirmation methods:\n\n#### Method 1: Confirm Parameter (Default - Works Everywhere)\n\n**Step 1: Preview (without confirm)**\n```json\n{\n  \"name\": \"docker_remove_volume\",\n  \"arguments\": {\n    \"name\": \"my-volume\"\n  }\n}\n```\n\nThis returns volume details and a warning message.\n\n**Step 2: Confirm (with confirm=true)**\n```json\n{\n  \"name\": \"docker_remove_volume\",\n  \"arguments\": {\n    \"name\": \"my-volume\",\n    \"confirm\": true\n  }\n}\n```\n\nThis actually removes the volume.\n\n#### Method 2: MCP Elicitation API (Advanced - Better UX)\n\nIf your MCP client (Cursor, Claude Desktop) supports Elicitation API, you can use interactive confirmation:\n\n```json\n{\n  \"name\": \"docker_remove_volume\",\n  \"arguments\": {\n    \"name\": \"my-volume\",\n    \"useElicitation\": true\n  }\n}\n```\n\nThis will show an interactive confirmation dialog in the client (if supported). The client will display a form asking for confirmation, and the operation proceeds only if the user accepts.\n\n**Note:** Elicitation API support depends on the MCP client. If the client doesn't support it, the server automatically falls back to the `confirm` parameter method.\n\n**Operations requiring confirmation:**\n- `docker_remove_volume` - Remove volumes\n- `docker_remove_container` - Remove containers\n- `docker_kill_container` - Kill containers\n- `docker_remove_image` - Remove images\n- `docker_remove_network` - Remove networks\n- `docker_prune_system` - Prune all unused resources\n- `docker_prune_images` - Prune unused images\n- `docker_prune_containers` - Prune stopped containers\n- `docker_prune_volumes` - Prune unused volumes\n- `docker_prune_networks` - Prune unused networks\n\n## Testing the Server\n\n### Quick Test\n\n1. Build the project:\n```bash\nnpm run build\n```\n\n2. Use the test script:\n```bash\n./test-server.sh\n```\n\nOr test manually:\n\n3. Test Docker connection:\n```bash\n# The server will exit with error if Docker is not accessible\nnode dist/index.js\n```\n\nIf Docker is running, you should see:\n```\nDocker MCP Server running on stdio\n```\n\n4. Test with a simple MCP request (using jq for JSON formatting):\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js | jq\n```\n\n**Note:** The server communicates via stdio, so it will wait for JSON-RPC requests. Press Ctrl+C to exit.\n\n### Manual Testing Steps\n\n1. **Start the server:**\n```bash\nnpm run build\nnpm start\n```\n\n2. **In another terminal, test with curl (if using HTTP transport) or use an MCP client**\n\n3. **Verify Docker operations work:**\n   - List containers: Use `docker_list_containers` tool\n   - Check system info: Use `docker_system_info` tool\n\n### Integration Testing\n\nFor full integration testing, you'll need an MCP client. The server communicates via stdio (standard input/output), so it's designed to work with MCP-compatible clients like:\n- Cursor IDE\n- Claude Desktop\n- Custom MCP clients\n\n### Debugging\n\nEnable verbose logging by checking stderr output. The server writes errors and status messages to stderr:\n\n```bash\n# Run and capture stderr\nnode dist/index.js 2> debug.log\n```\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/checklist-white.svg\"><img src=\"docs/icons/checklist.svg\" width=\"24\" height=\"24\" alt=\"Requirements\"></picture> Requirements\n\n- Node.js 18.0.0 or higher\n- Docker daemon running and accessible\n- **Supported Platforms:**\n  - Linux (x64, ARM64)\n  - macOS (Intel, Apple Silicon)\n  - Windows (x64, ARM64)\n- For remote Docker: Proper network access and TLS certificates (if using TLS)\n\n### Platform-Specific Notes\n\n- **Linux**: Requires Docker daemon with Unix socket at `/var/run/docker.sock`\n- **macOS**: Works with Docker Desktop. Automatically detects socket location.\n- **Windows**: Works with Docker Desktop. Uses named pipe `//./pipe/docker_engine`\n\n## Quick Start (Local Development)\n\n```bash\n# Clone and setup\ngit clone <repository-url>\ncd docker-mcp\nnpm install\n\n# Build\nnpm run build\n\n# Test\n./test-server.sh\n\n# Run\nnpm start\n# or for development\nnpm run dev\n```\n\n## License\n\nMIT\n\n## Testing with MCP Clients\n\n### Testing with Cursor (Local Development)\n\nIf you're developing locally and want to test with Cursor:\n\n1. Build the project:\n```bash\nnpm run build\n```\n\n2. Add to Cursor MCP configuration (usually in `.cursor/mcp.json` or similar):\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/docker-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nOr if using the binary:\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"/absolute/path/to/docker-mcp/bin/docker-mcp-server.js\"\n    }\n  }\n}\n```\n\n### Testing with Claude Desktop (Local Development)\n\nIf you're developing locally and want to test with Claude Desktop:\n\n1. Build the project:\n```bash\nnpm run build\n```\n\n2. Add to Claude Desktop configuration:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/docker-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Testing with MCP Inspector (CLI)\n\nYou can test the server using MCP Inspector or any MCP client:\n\n```bash\n# Build first\nnpm run build\n\n# The server communicates via stdio, so you can pipe commands to it\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js\n```\n\n## <picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/icons/handshake-white.svg\"><img src=\"docs/icons/handshake.svg\" width=\"24\" height=\"24\" alt=\"Contributing\"></picture> Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
  "bytes": 19378,
  "sha": "7b516e20dd303fa3b9e28e71903f0ffaee982451727e30ef41c45694123d27fc",
  "repo_slug": "alisaitteke/docker-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alisaitteke_docker_mcp_74c0f244/readme"
}