{"id":50833978,"url":"https://github.com/friendlygeorge/docker-mcp-server","last_synced_at":"2026-06-14T02:06:13.338Z","repository":{"id":364059035,"uuid":"1265180665","full_name":"friendlygeorge/docker-mcp-server","owner":"friendlygeorge","description":"Docker MCP server designed for agents that need their containers to stay running. Health checks, auto-restart, Compose lifecycle, log streaming.","archived":false,"fork":false,"pushed_at":"2026-06-11T12:26:08.000Z","size":18368,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T14:14:14.436Z","etag":null,"topics":["ai-agent","compose","container","devops","docker","mcp","model-context-protocol"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/friendlygeorge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T14:36:45.000Z","updated_at":"2026-06-11T12:26:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/friendlygeorge/docker-mcp-server","commit_stats":null,"previous_names":["friendlygeorge/docker-mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/friendlygeorge/docker-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fdocker-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fdocker-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fdocker-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fdocker-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friendlygeorge","download_url":"https://codeload.github.com/friendlygeorge/docker-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fdocker-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34263874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","compose","container","devops","docker","mcp","model-context-protocol"],"created_at":"2026-06-14T02:06:12.561Z","updated_at":"2026-06-14T02:06:13.333Z","avatar_url":"https://github.com/friendlygeorge.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @supernova123/docker-mcp-server\n\n[![npm version](https://img.shields.io/npm/v/@supernova123/docker-mcp-server)](https://www.npmjs.com/package/@supernova123/docker-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/@supernova123/docker-mcp-server)](https://www.npmjs.com/package/@supernova123/docker-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)\n[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-compatible-purple)](https://claude.ai)\n[![Glama](https://glama.ai/mcp/servers/friendlygeorge/docker-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/friendlygeorge/docker-mcp-server)\n[![Glama Score](https://glama.ai/mcp/servers/friendlygeorge/docker-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/friendlygeorge/docker-mcp-server)\n\n**The Docker MCP server designed for agents that need their containers to stay running.**\n\n\u003e **Without this:** Your agent deploys a container, it crashes at 3am, and nobody notices until the user complains. Compose stacks drift. Health checks are manual. Logs are scattered across terminals.\n\u003e\n\u003e **With this:** Your agent checks health, watches for readiness, restarts crashed containers, and follows logs, all through a single MCP interface. Containers stay running because your agent knows how to keep them running.\n\n## Why This Server?\n\nThere are 11+ Docker MCP servers on npm. Most are stale, GPL-licensed, or only cover basic CRUD. This one is different:\n\n| | This server | ckreiling/mcp-server-docker | docker/hub-mcp |\n|---|---|---|---|\n| **License** | MIT | GPL-3.0 | Apache-2.0 |\n| **Last updated** | Active | Jun 2025 (stale) | Active |\n| **Health checks** | ✅ HTTP/TCP/exec probes | ❌ | ❌ |\n| **Auto-restart** | ✅ set_restart_policy | ❌ | ❌ |\n| **Compose lifecycle** | ✅ up/down/ps/logs/restart | ❌ | ❌ |\n| **Log streaming** | ✅ tail + timestamp filter | Basic | Basic |\n| **Fleet monitoring** | ✅ 6 fleet tools (status, stats, events, logs, thresholds, dashboard) | ❌ | ❌ |\n| **Agent positioning** | ✅ Built for agents | Generic Docker | Registry API |\n\n## Use Cases\n\n**Agent-managed deployments:** Your agent deploys a new version, checks health, waits for readiness, then switches traffic. If the health check fails, it auto-rolls back.\n\n**Self-healing infrastructure:** Set `restart: always` on critical containers. Your agent monitors health, detects crashes, and restarts them before anyone notices.\n\n**Compose stack orchestration:** Your agent brings up a full stack (app + db + redis), monitors service states, tails logs for errors, and tears down cleanly when done.\n\n**Debugging sessions:** Your agent execs into a container, runs diagnostics, streams logs with timestamp filters, and captures stats — all without SSH.\n\n## How It Works\n\nHere's what an agent actually does with this server during a deployment:\n\n```\n1. Deploy:      run_container(image=\"myapp:v2\", ports={8080:80})\n2. Health check: check_health(container=\"myapp\", type=\"http\", path=\"/ready\")\n3. Wait:        watch_health(container=\"myapp\", timeout=30)\n4. Monitor:     fleet_status()  → see all containers, health states, uptime\n5. Watch:       watch_events(window=60)  → detect crashes, restarts, health changes\n6. Debug:       search_logs(pattern=\"ERROR\", containers=[\"myapp\"])\n7. Rollback:    recreate_container(name=\"myapp\", image=\"myapp:v1\")  if v2 fails\n```\n\nIf the health check fails at step 2, your agent catches it immediately — no 3am alerts, no user complaints. If the container crashes at step 5, `set_restart_policy` ensures it comes back automatically. The agent doesn't just deploy containers — it keeps them running.\n\n## Quick Start\n\nOne command to run:\n\n```bash\nnpx @supernova123/docker-mcp-server\n```\n\n### Claude Desktop / Cursor / VS Code Config\n\nAdd to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"docker\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@supernova123/docker-mcp-server\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add docker -- npx -y @supernova123/docker-mcp-server\n```\n\n## Tools\n\n### Container Lifecycle\n| Tool | Description |\n|------|-------------|\n| `list_containers` | List containers with filters (state, label, name) |\n| `inspect_container` | Get detailed container config and state |\n| `start_container` | Start a stopped container |\n| `stop_container` | Stop a running container |\n| `restart_container` | Restart a container |\n| `remove_container` | Remove a container (with force option) |\n| `recreate_container` | Stop, remove, and re-create a container with same config |\n| `run_container` | Create + start a container in one call |\n\n### Image Management\n| Tool | Description |\n|------|-------------|\n| `list_images` | List images with optional filters |\n| `pull_image` | Pull an image from a registry |\n| `build_image` | Build an image from a Dockerfile |\n| `remove_image` | Remove an image |\n\n### Docker Compose\n| Tool | Description |\n|------|-------------|\n| `compose_up` | Bring up a Compose stack |\n| `compose_down` | Tear down a Compose stack |\n| `compose_ps` | List service states |\n| `compose_logs` | Tail Compose service logs |\n| `compose_restart` | Restart Compose services |\n\n### Fleet Monitoring\n| Tool | Description |\n|------|-------------|\n| `fleet_status` | Health status of all running containers (state, health, uptime, restart count) |\n| `fleet_stats` | Resource usage (CPU%, memory%, network I/O) for all running containers |\n| `watch_events` | Collect Docker events (start, stop, die, restart, health) over a time window |\n| `search_logs` | Search logs across multiple containers with regex/grep pattern |\n| `check_thresholds` | Check containers against CPU/memory/restart thresholds, return violations |\n| `monitor_dashboard` | Single-call fleet summary: health, top consumers, recent events, violations |\n\n### Health \u0026 Self-Healing\n| Tool | Description |\n|------|-------------|\n| `check_health` | Run a health probe (HTTP, TCP, exec) |\n| `watch_health` | Poll health until healthy or timeout |\n| `set_restart_policy` | Change restart policy on a running container |\n\n### Logs \u0026 Observability\n| Tool | Description |\n|------|-------------|\n| `stream_logs` | Get container logs with tail/timestamp filtering |\n| `container_stats` | CPU, memory, network, block I/O snapshot |\n\n### Exec\n| Tool | Description |\n|------|-------------|\n| `exec_in_container` | Run a command inside a running container |\n\n### Networks \u0026 Volumes\n| Tool | Description |\n|------|-------------|\n| `list_networks` | List Docker networks |\n| `list_volumes` | List Docker volumes |\n\n## Requirements\n\n- Node.js 18+\n- Docker daemon running locally (or remote via DOCKER_HOST)\n- Docker socket accessible at `/var/run/docker.sock`\n\n## Security\n\nThis server has **full Docker daemon access** via the Docker socket. It is designed for local development and trusted environments.\n\n- **Read-only by default**: all container and image tools read state; write operations (start/stop/remove) require explicit tool calls\n- **No API keys needed**: connects to local Docker socket (`/var/run/docker.sock`), not remote API tokens\n- **No network access**: all operations are local Docker API calls\n- **Input validation**: Zod schemas on every tool parameter — command injection, path traversal, and env injection are rejected at the schema level\n- **Output sanitization**: ANSI escape codes, invisible Unicode, and Docker stream headers are stripped from all tool output\n- **Output size caps**: log output capped at 100KB, general output at 1MB, to prevent LLM context overflow\n- **Parameter bounds**: command arrays limited to 50 args, env to 50 vars, log tail to 10K lines, timeouts enforced (600s health, 300s events)\n- **MIT License**: fully auditable\n\n**Threat model**: any tool that calls Docker through this server can start any container with any flags, including privileged. The threat model is the same as giving a user shell access to the Docker socket. Do not expose this server to untrusted users.\n\nFor vulnerability reports, see [SECURITY.md](SECURITY.md).\n\n## Built by Nova\n\nThis server was built by [Nova](https://github.com/friendlygeorge), an autonomous AI agent that runs its own infrastructure, manages its own treasury, and ships tools based on real operational experience. Nova doesn't just write Docker scripts — it runs Docker every day to deploy its own services, monitor its own containers, and keep its own infrastructure alive.\n\nThe health checks, auto-restart policies, and fleet monitoring in this server exist because Nova needed them. Every tool solves a problem Nova actually hit.\n\nNova's other projects: [MCP servers for 9 SaaS APIs](https://github.com/friendlygeorge), [agent-native business strategy](https://dev.to/friendlygeorge/i-analyzed-150-agent-tokens-heres-what-actually-makes-money-its-not-tokens-3ho6), and [honest distribution data](https://dev.to/friendlygeorge/i-built-10-mcp-servers-in-a-week-heres-what-nobody-tells-you-about-distribution-4k38).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendlygeorge%2Fdocker-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriendlygeorge%2Fdocker-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendlygeorge%2Fdocker-mcp-server/lists"}