@supernova123/docker-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @supernova123/docker-mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@supernova123/docker-mcp-server)](https://www.npmjs.com/package/@supernova123/docker-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/@supernova123/docker-mcp-server)](https://www.npmjs.com/package/@supernova123/docker-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)
+[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-compatible-purple)](https://claude.ai)
+
+**The Docker MCP server designed for agents that need their containers to stay running.**
+
+> **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.
+>
+> **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.
+
+## Why This Server?
+
+There are 11+ Docker MCP servers on npm. Most are stale, GPL-licensed, or only cover basic CRUD. This one is different:
+
+| | This server | ckreiling/mcp-server-docker | docker/hub-mcp |
+|---|---|---|---|
+| **License** | MIT | GPL-3.0 | Apache-2.0 |
+| **Last updated** | Active | Jun 2025 (stale) | Active |
+| **Health checks** | ✅ HTTP/TCP/exec probes | ❌ | ❌ |
+| **Auto-restart** | ✅ set_restart_policy | ❌ | ❌ |
+| **Compose lifecycle** | ✅ up/down/ps/logs/restart | ❌ | ❌ |
+| **Log streaming** | ✅ tail + timestamp filter | Basic | Basic |
+| **Agent positioning** | ✅ Built for agents | Generic Docker | Registry API |
+
+## Quick Start
+
+One command to run:
+
+```bash
+npx @supernova123/docker-mcp-server
+```
+
+### Claude Desktop / Cursor / VS Code Config
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "docker": {
+      "command": "npx",
+      "args": ["-y", "@supernova123/docker-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add docker -- npx -y @supernova123/docker-mcp-server
+```
+
+## Tools
+
+### Container Lifecycle
+| Tool | Description |
+|------|-------------|
+| `list_containers` | List containers with filters (state, label, name) |
+| `inspect_container` | Get detailed container config and state |
+| `start_container` | Start a stopped container |
+| `stop_container` | Stop a running container |
+| `restart_container` | Restart a container |
+| `remove_container` | Remove a container (with force option) |
+| `recreate_container` | Stop, remove, and re-create a container with same config |
+| `run_container` | Create + start a container in one call |
+
+### Image Management
+| Tool | Description |
+|------|-------------|
+| `list_images` | List images with optional filters |
+| `pull_image` | Pull an image from a registry |
+| `build_image` | Build an image from a Dockerfile |
+| `remove_image` | Remove an image |
+
+### Docker Compose
+| Tool | Description |
+|------|-------------|
+| `compose_up` | Bring up a Compose stack |
+| `compose_down` | Tear down a Compose stack |
+| `compose_ps` | List service states |
+| `compose_logs` | Tail Compose service logs |
+| `compose_restart` | Restart Compose services |
+
+### Health & Self-Healing
+| Tool | Description |
+|------|-------------|
+| `check_health` | Run a health probe (HTTP, TCP, exec) |
+| `watch_health` | Poll health until healthy or timeout |
+| `set_restart_policy` | Change restart policy on a running container |
+
+### Logs & Observability
+| Tool | Description |
+|------|-------------|
+| `stream_logs` | Get container logs with tail/timestamp filtering |
+| `container_stats` | CPU, memory, network, block I/O snapshot |
+
+### Exec
+| Tool | Description |
+|------|-------------|
+| `exec_in_container` | Run a command inside a running container |
+
+### Networks & Volumes
+| Tool | Description |
+|------|-------------|
+| `list_networks` | List Docker networks |
+| `list_volumes` | List Docker volumes |
+
+## Requirements
+
+- Node.js 18+
+- Docker daemon running locally (or remote via DOCKER_HOST)
+- Docker socket accessible at `/var/run/docker.sock`
+
+## Security
+
+- **Read-only by default**: all container and image tools read state; write operations (start/stop/remove) require explicit tool calls
+- **No API keys needed**: connects to local Docker daemon via socket
+- **No network access**: all operations are local Docker API calls
+- **MIT License**: fully auditable
+
+## License
+
+MIT

package/dist/docker.d.ts

@@ -0,0 +1,12 @@
+import Dockerode from "dockerode";
+export interface DockerClientOptions {
+    socketPath?: string;
+    host?: string;
+    port?: number;
+}
+export declare function createDockerClient(options?: DockerClientOptions): Dockerode;
+export declare function formatError(error: unknown): string;
+export declare function formatContainer(container: Dockerode.ContainerInfo): Record<string, unknown>;
+export declare function formatImage(image: Dockerode.ImageInfo): Record<string, unknown>;
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=docker.d.ts.map

package/dist/docker.js

@@ -0,0 +1,58 @@
+import Dockerode from "dockerode";
+export function createDockerClient(options) {
+    if (options?.socketPath) {
+        return new Dockerode({ socketPath: options.socketPath });
+    }
+    if (options?.host && options?.port) {
+        return new Dockerode({ host: options.host, port: options.port });
+    }
+    // Default: local socket
+    return new Dockerode({ socketPath: "/var/run/docker.sock" });
+}
+export function formatError(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return String(error);
+}
+export function formatContainer(container) {
+    return {
+        id: container.Id.substring(0, 12),
+        name: container.Names[0]?.replace(/^\//, ""),
+        image: container.Image,
+        state: container.State,
+        status: container.Status,
+        created: new Date(container.Created * 1000).toISOString(),
+        ports: container.Ports.map((p) => ({
+            private: p.PrivatePort,
+            public: p.PublicPort,
+            type: p.Type,
+        })),
+        labels: container.Labels,
+        mounts: container.Mounts.map((m) => ({
+            type: m.Type,
+            source: m.Source,
+            destination: m.Destination,
+            mode: m.Mode,
+            rw: m.RW,
+        })),
+    };
+}
+export function formatImage(image) {
+    return {
+        id: image.Id.substring(0, 19),
+        tags: image.RepoTags || ["<none>:<none>"],
+        size: image.Size,
+        created: new Date(image.Created).toISOString(),
+    };
+}
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+//# sourceMappingURL=docker.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDockerClient } from "./docker.js";
+import { createServer } from "./server.js";
+async function main() {
+    const docker = createDockerClient();
+    const server = createServer(docker);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("Docker MCP Server running on stdio\n");
+}
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import Dockerode from "dockerode";
+export declare function createServer(docker: Dockerode): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerContainerTools } from "./tools/container.js";
+import { registerImageTools } from "./tools/image.js";
+import { registerComposeTools } from "./tools/compose.js";
+import { registerHealthTools } from "./tools/health.js";
+import { registerLogsTools } from "./tools/logs.js";
+import { registerExecTools } from "./tools/exec.js";
+import { registerNetworkTools } from "./tools/network.js";
+export function createServer(docker) {
+    const server = new McpServer({
+        name: "docker-mcp-server",
+        version: "0.1.0",
+    });
+    // Register all tool categories
+    registerContainerTools(server, docker);
+    registerImageTools(server, docker);
+    registerComposeTools(server);
+    registerHealthTools(server, docker);
+    registerLogsTools(server, docker);
+    registerExecTools(server, docker);
+    registerNetworkTools(server, docker);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/compose.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerComposeTools(server: McpServer): void;
+//# sourceMappingURL=compose.d.ts.map

package/dist/tools/compose.js

@@ -0,0 +1,95 @@
+import { execSync, exec as execCb } from "child_process";
+import { promisify } from "util";
+import { ComposeUpSchema, ComposeDownSchema, ComposePsSchema, ComposeLogsSchema, ComposeRestartSchema, } from "../types.js";
+import { formatError } from "../docker.js";
+const execAsync = promisify(execCb);
+function runCompose(path, args) {
+    try {
+        const result = execSync(`docker compose -f ${path} ${args.join(" ")}`, {
+            encoding: "utf-8",
+            timeout: 30000,
+        });
+        return result.trim();
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(err.stderr || err.stdout || formatError(error));
+    }
+}
+export function registerComposeTools(server) {
+    server.tool("compose_up", "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.", ComposeUpSchema.shape, async (params) => {
+        try {
+            const args = ["up", "-d"];
+            if (params.build)
+                args.push("--build");
+            if (params.services?.length)
+                args.push(...params.services);
+            const output = runCompose(params.path, args);
+            return { content: [{ type: "text", text: output || "Compose services started." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("compose_down", "Tear down Docker Compose services. Optionally remove named volumes.", ComposeDownSchema.shape, async (params) => {
+        try {
+            const args = ["down"];
+            if (params.volumes)
+                args.push("-v");
+            if (params.timeout)
+                args.push(`--timeout ${params.timeout}`);
+            const output = runCompose(params.path, args);
+            return { content: [{ type: "text", text: output || "Compose services stopped." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("compose_ps", "List service states across a Docker Compose stack.", ComposePsSchema.shape, async (params) => {
+        try {
+            const output = runCompose(params.path, ["ps", "--format", "json"]);
+            const lines = output.split("\n").filter(Boolean);
+            const services = lines.map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return { raw: line };
+                }
+            });
+            return { content: [{ type: "text", text: JSON.stringify(services, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("compose_logs", "Tail logs from Docker Compose services. Supports filtering by service and line count.", ComposeLogsSchema.shape, async (params) => {
+        try {
+            const args = ["logs", "--tail", String(params.tail ?? 100)];
+            if (params.follow)
+                args.push("-f");
+            if (params.services?.length)
+                args.push(...params.services);
+            const output = runCompose(params.path, args);
+            return { content: [{ type: "text", text: output || "No logs found." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("compose_restart", "Restart Docker Compose services. Restart specific services or the entire stack.", ComposeRestartSchema.shape, async (params) => {
+        try {
+            const args = ["restart"];
+            if (params.timeout)
+                args.push(`--timeout ${params.timeout}`);
+            if (params.services?.length)
+                args.push(...params.services);
+            const output = runCompose(params.path, args);
+            return { content: [{ type: "text", text: output || "Compose services restarted." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+//# sourceMappingURL=compose.js.map

package/dist/tools/container.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerContainerTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=container.d.ts.map

package/dist/tools/container.js

@@ -0,0 +1,140 @@
+import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, } from "../types.js";
+import { formatContainer, formatError } from "../docker.js";
+export function registerContainerTools(server, docker) {
+    server.tool("list_containers", "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.", ListContainersSchema.shape, async (params) => {
+        try {
+            const containers = await docker.listContainers({
+                all: params.all ?? false,
+                filters: JSON.stringify({
+                    ...(params.label ? { label: params.label } : {}),
+                    ...(params.name ? { name: [`/${params.name}`] } : {}),
+                    ...(params.state ? { status: [params.state] } : {}),
+                }),
+            });
+            const results = containers.map(formatContainer);
+            return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("inspect_container", "Get detailed configuration and state of a Docker container by ID or name.", InspectContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            const info = await container.inspect();
+            return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("start_container", "Start a stopped Docker container by ID or name.", StartContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            await container.start();
+            return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("stop_container", "Stop a running Docker container by ID or name with optional timeout.", StopContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            await container.stop({ t: params.timeout ?? 10 });
+            return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("restart_container", "Restart a Docker container by ID or name with optional timeout.", RestartContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            await container.restart({ t: params.timeout ?? 10 });
+            return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("remove_container", "Remove a Docker container by ID or name. Use force to remove running containers.", RemoveContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            await container.remove({ force: params.force ?? false });
+            return { content: [{ type: "text", text: `Container ${params.container_id} removed.` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("recreate_container", "Recreate a container with the same configuration (stop, remove, re-create). Useful for applying config changes.", RecreateContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            const info = await container.inspect();
+            // Stop and remove
+            try {
+                await container.stop({ t: params.timeout ?? 10 });
+            }
+            catch { /* already stopped */ }
+            await container.remove({ force: true });
+            // Re-create with same config
+            const createOpts = {
+                name: info.Name.replace(/^\//, ""),
+                Image: info.Config.Image,
+                Env: info.Config.Env,
+                Cmd: info.Config.Cmd,
+                WorkingDir: info.Config.WorkingDir,
+                Labels: info.Config.Labels || {},
+                HostConfig: {
+                    Binds: info.HostConfig?.Binds,
+                    PortBindings: info.HostConfig?.PortBindings,
+                    RestartPolicy: info.HostConfig?.RestartPolicy,
+                    NetworkMode: info.HostConfig?.NetworkMode,
+                },
+            };
+            const newContainer = await docker.createContainer(createOpts);
+            await newContainer.start();
+            return {
+                content: [{ type: "text", text: `Container recreated and started. New ID: ${newContainer.id.substring(0, 12)}` }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("run_container", "Create and start a new Docker container with one command. Supports image, env, ports, volumes, restart policy, and command override.", RunContainerSchema.shape, async (params) => {
+        try {
+            const createOpts = {
+                Image: params.image,
+                name: params.name,
+                Env: params.env ? Object.entries(params.env).map(([k, v]) => `${k}=${v}`) : undefined,
+                Cmd: params.command,
+                ExposedPorts: params.ports
+                    ? Object.fromEntries(Object.keys(params.ports).map((k) => [k, {}]))
+                    : undefined,
+                HostConfig: {
+                    PortBindings: params.ports
+                        ? Object.fromEntries(Object.entries(params.ports).map(([containerPort, hostBinding]) => [
+                            containerPort,
+                            [{ HostPort: hostBinding }],
+                        ]))
+                        : undefined,
+                    Binds: params.volumes,
+                    RestartPolicy: params.restart_policy
+                        ? { Name: params.restart_policy, MaximumRetryCount: 0 }
+                        : undefined,
+                },
+            };
+            const container = await docker.createContainer(createOpts);
+            await container.start();
+            return {
+                content: [{ type: "text", text: `Container created and started. ID: ${container.id.substring(0, 12)}` }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+//# sourceMappingURL=container.js.map

package/dist/tools/exec.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerExecTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=exec.d.ts.map

package/dist/tools/exec.js

@@ -0,0 +1,39 @@
+import { ExecInContainerSchema } from "../types.js";
+import { formatError } from "../docker.js";
+export function registerExecTools(server, docker) {
+    server.tool("exec_in_container", "Execute a command inside a running Docker container. Returns stdout, stderr, and exit code.", ExecInContainerSchema.shape, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            const exec = await container.exec({
+                Cmd: params.command,
+                AttachStdout: true,
+                AttachStderr: true,
+                WorkingDir: params.working_dir,
+                Env: params.env ? Object.entries(params.env).map(([k, v]) => `${k}=${v}`) : undefined,
+            });
+            const stream = await exec.start({});
+            const output = await new Promise((resolve) => {
+                let data = "";
+                stream.on("data", (chunk) => { data += chunk.toString(); });
+                stream.on("end", () => resolve(data));
+            });
+            const inspect = await exec.inspect();
+            const cleanOutput = output.replace(/^[\x00-\x0f]{8}/gm, "");
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            exitCode: inspect.ExitCode,
+                            stdout: cleanOutput,
+                            stderr: "",
+                        }, null, 2),
+                    }],
+                isError: inspect.ExitCode !== 0,
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+//# sourceMappingURL=exec.js.map

package/dist/tools/health.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerHealthTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=health.d.ts.map