{"_id":"docker-mcp","name":"docker-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"docker-mcp","version":"1.0.0","description":"A Model Context Protocol (MCP) server that enables AI agents to interact with Docker containers locally or remotely via SSH. Provides comprehensive Docker management capabilities including container operations, logs, monitoring, and cleanup.","type":"module","main":"dist/index.js","bin":{"docker-mcp":"dist/index.js"},"keywords":["mcp","model-context-protocol","docker","containers","ssh","remote-docker","ai-agent","docker-management","dockerode","devops"],"author":{"name":"Son Dang","url":"https://github.com/sondt2709"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/sondt2709/docker-mcp.git"},"bugs":{"url":"https://github.com/sondt2709/docker-mcp/issues"},"homepage":"https://github.com/sondt2709/docker-mcp#readme","engines":{"node":">=18.0.0"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","test":"jest","prepare":"npm run build","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.15.1","dockerode":"^4.0.7","dockerode-compose":"^1.4.0","ssh2":"^1.16.0","zod":"^3.22.4"},"devDependencies":{"@types/dockerode":"^3.3.42","@types/node":"^20.19.7","tsx":"^4.20.3","typescript":"^5.8.3"},"_id":"docker-mcp@1.0.0","gitHead":"6a0008429c15072739c3a5f45c73630492aa57f6","types":"./dist/index.d.ts","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-eCYi8FZlParyV+sO4YtTDz7CPeOPydkT8q5LUHkd3OKGAdY+GPbm+XFiOF7FjPRahe6Ecbvl4nCRoe8TTMNiiA==","shasum":"d4093a89b6127e9c511df688e14886846c76dc78","tarball":"https://registry.npmjs.org/docker-mcp/-/docker-mcp-1.0.0.tgz","fileCount":80,"unpackedSize":184903,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEmFe9CC6tYrIaOMYqJHN+kmjxgLRMFR+hRKQseiXDQ/AiATX0mUTDaRzKI8kqC6tFF/84hzQVpS3XhmChJ4RBFRnA=="}]},"_npmUser":{"name":"sondt2709","email":"sondt.2709@gmail.com"},"directories":{},"maintainers":[{"name":"sondt2709","email":"sondt.2709@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/docker-mcp_1.0.0_1752382709990_0.00033206189748802295"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-13T04:58:29.989Z","1.0.0":"2025-07-13T04:58:30.175Z","modified":"2025-07-13T04:58:30.539Z"},"maintainers":[{"name":"sondt2709","email":"sondt.2709@gmail.com"}],"description":"A Model Context Protocol (MCP) server that enables AI agents to interact with Docker containers locally or remotely via SSH. Provides comprehensive Docker management capabilities including container operations, logs, monitoring, and cleanup.","homepage":"https://github.com/sondt2709/docker-mcp#readme","keywords":["mcp","model-context-protocol","docker","containers","ssh","remote-docker","ai-agent","docker-management","dockerode","devops"],"repository":{"type":"git","url":"git+https://github.com/sondt2709/docker-mcp.git"},"author":{"name":"Son Dang","url":"https://github.com/sondt2709"},"bugs":{"url":"https://github.com/sondt2709/docker-mcp/issues"},"license":"MIT","readme":"# Docker MCP\n\nDocker MCP is a MCP tool that help AI Agent interact with docker containers in a specific VM or local machine, so that user (who use AI Agent) can manage and troubleshoot containers without any docker knowledge.\n\nStack: NodeJS LTS, npm, dockerode, MCP.\n\n## Features\n\n- Know and run docker, docker compose commands in a specific VM or local machine.\n- Support remote Docker daemon via SSH connections.\n- View docker network, exposed port, logs (with specific time range), etc...\n- Detect container restart loop\n- Cleanup unused resources (images, volumes...)\n\n## Remote Docker Support\n\nThe Docker MCP server supports connecting to remote Docker daemons via SSH. This allows you to manage Docker containers on remote VMs or servers from your local machine.\n\n### Quick Start (Recommended)\n\n1. **Set up SSH tunnel:**\n   ```bash\n   ./scripts/setup-ssh-tunnel.sh your-remote-host\n   ```\n\n2. **Connect via tunnel:**\n   ```bash\n   DOCKER_MCP_HOST=tcp://localhost:2375 node dist/index.js\n   ```\n\n### Configuration Methods\n\n#### 1. SSH Tunneling (Stable)\n\nUse the provided script to create an SSH tunnel:\n\n```bash\n# Using SSH config host\n./scripts/setup-ssh-tunnel.sh my-vm\n\n# Using explicit user@host\n./scripts/setup-ssh-tunnel.sh ubuntu@192.168.1.100\n\n# Then connect via tunnel\nDOCKER_MCP_HOST=tcp://localhost:2375 node dist/index.js\n```\n\n#### 2. Direct SSH Connection (Recommended)\n\nUse the `ssh://` protocol format for direct SSH connections to remote Docker daemons:\n\n```bash\n# Direct SSH connection using SSH config host\nexport DOCKER_MCP_HOST=ssh://my-vm\n\n# Direct SSH connection with explicit host\nexport DOCKER_MCP_HOST=ssh://192.168.1.100\nexport DOCKER_MCP_USERNAME=ubuntu\nexport DOCKER_MCP_PRIVATE_KEY=~/.ssh/id_rsa\n\n# Force local Docker daemon (default behavior)\nexport DOCKER_MCP_LOCAL=true\n```\n\n#### 3. SSH Config Integration\n\nThe server automatically reads SSH configuration from `~/.ssh/config`. Define your remote hosts there:\n\n```ssh\nHost my-vm\n    HostName 192.168.1.100\n    User ubuntu\n    Port 22\n    IdentityFile ~/.ssh/id_rsa\n```\n\nThen simply use:\n```bash\nexport DOCKER_MCP_HOST=ssh://my-vm\n```\n\n📖 **For detailed remote Docker setup instructions, see [REMOTE_DOCKER.md](REMOTE_DOCKER.md)**\n\n#### 4. Full Environment Variable Configuration\n\n```bash\n# Required - use ssh:// protocol format\nexport DOCKER_MCP_HOST=ssh://192.168.1.100    # SSH host with ssh:// prefix\nexport DOCKER_MCP_USERNAME=ubuntu             # SSH username\n\n# Optional\nexport DOCKER_MCP_PORT=22                     # SSH port (default: 22)\nexport DOCKER_MCP_PRIVATE_KEY=~/.ssh/id_rsa   # SSH private key path\nexport DOCKER_MCP_PASSPHRASE=mypassphrase     # SSH key passphrase\nexport DOCKER_MCP_SOCKET_PATH=/var/run/docker.sock  # Remote Docker socket\nexport DOCKER_MCP_TIMEOUT=10000               # Connection timeout (ms)\n```\n\n### Usage Examples\n\n#### Local Docker (Default)\n\n```bash\n# No configuration needed - auto-detects local Docker\nnpm start\n\n# Or explicitly force local\nDOCKER_MCP_LOCAL=true npm start\n```\n\n#### Remote Docker via SSH Config\n\n```bash\n# Uses SSH config for host details with ssh:// protocol\nDOCKER_MCP_HOST=ssh://my-vm npm start\n```\n\n#### Remote Docker with Full Configuration\n\n```bash\n# Explicit configuration with ssh:// protocol\nDOCKER_MCP_HOST=ssh://192.168.1.100 \\\nDOCKER_MCP_USERNAME=ubuntu \\\nDOCKER_MCP_PRIVATE_KEY=~/.ssh/id_rsa \\\nnpm start\n```\n\n### Command Line Options\n\n```bash\n# Show configuration help\nnode dist/index.js --help\n\n# Show current configuration\nnode dist/index.js --config\n```\n\n## MCP tools\n\nBased on the updated README.md with the added \"Cleanup unused resources\" feature, here's the updated and expanded tool list for your Docker MCP server:\n\n### Core Container Management Tools\n\n1. **list_containers** - List all containers with their status, names, and basic info\n2. **inspect_container** - Get detailed information about a specific container\n3. **start_container** - Start a stopped container\n4. **stop_container** - Stop a running container\n5. **restart_container** - Restart a container\n6. **remove_container** - Remove a container\n7. **create_container** - Create a new container from an image\n\n### Container Monitoring & Debugging Tools\n\n8. **get_container_logs** - Retrieve container logs with optional time range filtering\n9. **follow_container_logs** - Stream live logs from a container\n10. **get_container_stats** - Get real-time resource usage statistics\n11. **execute_in_container** - Execute commands inside a running container\n12. **detect_restart_loops** - Custom tool to detect containers that are restarting frequently\n\n### Docker Compose Tools\n\n13. **compose_up** - Start services defined in docker-compose.yml\n14. **compose_down** - Stop and remove compose services\n15. **compose_pull** - Pull latest images for compose services\n16. **compose_logs** - Get logs from compose services\n\n### Image Management Tools\n\n17. **list_images** - List available Docker images\n18. **pull_image** - Pull an image from a registry\n19. **remove_image** - Remove an image\n20. **inspect_image** - Get detailed image information\n\n### Network & Volume Tools\n\n21. **list_networks** - List Docker networks\n22. **inspect_network** - Get network details including connected containers\n23. **list_volumes** - List Docker volumes\n24. **inspect_volume** - Get volume details\n\n## System Information Tools\n\n25. **docker_info** - Get Docker system information\n26. **docker_version** - Get Docker version information\n27. **system_df** - Show Docker disk usage\n\n### Cleanup & Pruning Tools\n\n28. **cleanup_unused_images** - Remove unused/dangling images (docker image prune)\n29. **cleanup_unused_volumes** - Remove unused volumes (docker volume prune)\n30. **cleanup_unused_networks** - Remove unused networks (docker network prune)\n31. **cleanup_unused_containers** - Remove stopped containers (docker container prune)\n32. **cleanup_build_cache** - Remove build cache (docker buildx prune)\n33. **cleanup_all** - Comprehensive cleanup of all unused resources\n34. **get_cleanup_summary** - Show what would be cleaned up without actually removing\n\n### Advanced Troubleshooting Tools\n\n35. **container_processes** - List processes running inside a container\n36. **container_port_mappings** - Show port mappings for containers\n37. **container_file_changes** - Show filesystem changes in a container\n38. **export_container** - Export container as tar archive\n39. **copy_from_container** - Copy files from container to host\n40. **copy_to_container** - Copy files from host to container\n\nThe cleanup tools would utilize dockerode's built-in pruning methods:\n\n- `docker.pruneImages()` for unused images\n- `docker.pruneVolumes()` for unused volumes\n- `docker.pruneNetworks()` for unused networks\n- `docker.pruneContainers()` for stopped containers\n- `docker.pruneBuilder()` for build cache\n\n## Folder Structure\n\n```\ndocker-mcp/\n├── src/\n│   ├── index.ts                    # Main entry point - server setup and transport\n│   ├── server/\n│   │   ├── DockerMcpServer.ts     # Main MCP server class\n│   │   └── config.ts              # Server configuration\n│   ├── tools/\n│   │   ├── index.ts               # Tool registry/exports\n│   │   ├── docker_container_list.ts\n│   │   ├── docker_container_inspect.ts\n│   │   ├── docker_container_start.ts\n│   │   ├── docker_container_stop.ts\n│   │   ├── docker_container_restart.ts\n│   │   ├── docker_container_remove.ts\n│   │   ├── docker_container_create.ts\n│   │   ├── docker_container_logs.ts\n│   │   ├── docker_container_logs_follow.ts\n│   │   ├── docker_container_stats.ts\n│   │   ├── docker_container_exec.ts\n│   │   ├── docker_container_detect_restart_loops.ts\n│   │   ├── docker_container_processes.ts\n│   │   ├── docker_container_port_mappings.ts\n│   │   ├── docker_container_file_changes.ts\n│   │   ├── docker_container_export.ts\n│   │   ├── docker_container_copy_from.ts\n│   │   ├── docker_container_copy_to.ts\n│   │   ├── docker_compose_up.ts\n│   │   ├── docker_compose_down.ts\n│   │   ├── docker_compose_pull.ts\n│   │   ├── docker_compose_logs.ts\n│   │   ├── docker_image_list.ts\n│   │   ├── docker_image_pull.ts\n│   │   ├── docker_image_remove.ts\n│   │   ├── docker_image_inspect.ts\n│   │   ├── docker_network_list.ts\n│   │   ├── docker_network_inspect.ts\n│   │   ├── docker_volume_list.ts\n│   │   ├── docker_volume_inspect.ts\n│   │   ├── docker_system_info.ts\n│   │   ├── docker_system_version.ts\n│   │   ├── docker_system_df.ts\n│   │   ├── docker_cleanup_unused_images.ts\n│   │   ├── docker_cleanup_unused_volumes.ts\n│   │   ├── docker_cleanup_unused_networks.ts\n│   │   ├── docker_cleanup_unused_containers.ts\n│   │   ├── docker_cleanup_build_cache.ts\n│   │   ├── docker_cleanup_all.ts\n│   │   └── docker_cleanup_summary.ts\n│   ├── services/\n│   │   ├── DockerService.ts       # Docker API wrapper using dockerode\n│   │   └── ComposeService.ts      # Docker Compose wrapper using dockerode-compose\n│   ├── types/\n│   │   ├── docker.ts              # Docker-related type definitions\n│   │   ├── mcp.ts                 # MCP-specific types\n│   │   └── index.ts               # Type exports\n│   └── utils/\n│       ├── validation.ts          # Input validation helpers\n│       ├── error.ts               # Error handling utilities\n│       └── logger.ts              # Logging utilities\n├── config/\n│   ├── default.json               # Default configuration\n│   └── production.json            # Production configuration\n├── tests/\n│   ├── tools/\n│   │   ├── docker_container_*.test.ts\n│   │   ├── docker_compose_*.test.ts\n│   │   ├── docker_image_*.test.ts\n│   │   ├── docker_network_*.test.ts\n│   │   ├── docker_volume_*.test.ts\n│   │   ├── docker_system_*.test.ts\n│   │   └── docker_cleanup_*.test.ts\n│   ├── services/\n│   └── utils/\n├── examples/\n│   ├── stdio-server.ts            # Example stdio server\n│   ├── http-server.ts             # Example HTTP server\n│   └── client-example.ts          # Example client usage\n├── docker/\n│   ├── Dockerfile                 # Container for the MCP server\n│   └── docker-compose.yml         # For testing with Docker\n├── docs/\n│   ├── API.md                     # Tool documentation\n│   ├── SETUP.md                   # Setup instructions\n│   └── EXAMPLES.md                # Usage examples\n├── .github/\n│   └── workflows/\n│       └── ci.yml                 # GitHub Actions CI\n├── package.json\n├── tsconfig.json\n├── yarn.lock\n├── .gitignore\n├── .eslintrc.js\n├── .prettierrc\n└── README.md\n````\n\n## Testing and Usage\n\n### Running the Server\n\nTo start the Docker MCP server:\n\n```bash\n# Development mode (with auto-reload)\nnpm run dev\n\n# Production mode\nnpm run build\nnpm start\n```\n\n### Testing the Server\n\nThe server can be tested using JSON-RPC 2.0 requests via stdio. Here are some example commands:\n\n#### List all available tools\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/list\", \"params\": {}}' | node dist/index.js\n```\n\n#### List all Docker containers\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_container_list\", \"arguments\": {\"all\": true}}}' | node dist/index.js\n```\n\n#### Get Docker version information\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_system_version\", \"arguments\": {}}}' | node dist/index.js\n```\n\n#### Inspect a specific container\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_container_inspect\", \"arguments\": {\"containerId\": \"container_name\"}}}' | node dist/index.js\n```\n\n#### Start a container\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_container_start\", \"arguments\": {\"containerId\": \"container_name\"}}}' | node dist/index.js\n```\n\n#### Get container logs\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_container_logs\", \"arguments\": {\"containerId\": \"container_name\", \"tail\": 10, \"timestamps\": true}}}' | node dist/index.js\n```\n\n#### Stop a container\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"docker_container_stop\", \"arguments\": {\"containerId\": \"container_name\"}}}' | node dist/index.js\n```\n\n### Available Tools\n\nThe server provides the following MCP tools:\n\n1. **docker_container_list** - List all containers with their status, names, and basic info\n2. **docker_container_inspect** - Get detailed information about a specific container\n3. **docker_container_start** - Start a stopped container\n4. **docker_container_stop** - Stop a running container\n5. **docker_container_restart** - Restart a container\n6. **docker_container_logs** - Get container logs with optional time range filtering and timestamps\n7. **docker_system_info** - Get Docker system information\n8. **docker_system_version** - Get Docker version information\n\n### Docker Socket Configuration\n\nThe server automatically detects the appropriate Docker socket path:\n\n**Local Docker:**\n- OrbStack: `~/.orbstack/run/docker.sock`\n- Docker Desktop: `~/.docker/run/docker.sock`\n- Default Unix: `/var/run/docker.sock`\n\n**Remote Docker:**\n- Default: `/var/run/docker.sock` (on remote host)\n- Customizable via `DOCKER_MCP_SOCKET_PATH` environment variable\n\n### Connection Requirements\n\n**Local Docker:**\n- Docker daemon must be running and accessible\n- The server needs appropriate permissions to access the Docker socket\n- Node.js and npm must be installed for development\n\n**Remote Docker:**\n- SSH access to the remote host\n- Docker daemon running on the remote host\n- SSH key-based authentication (recommended)\n- Network connectivity between local and remote hosts\n","readmeFilename":"README.md","_rev":"1-5d77753faee9925d120000f921fd4b83"}