mcp-server-docker

Instructions

Implementation Reference

• src/docker.ts:48-59 (handler)

  The main handler function that executes the list_containers tool logic. It calls the Docker API to list containers and maps the results to a simplified ContainerInfo format with formatted fields for id, name, image, state, status, ports, and creation date.

  export async function listContainers(all: boolean): Promise<ContainerInfo[]> {
    const containers = await docker.listContainers({ all });
    return containers.map((c) => ({
      id: c.Id.slice(0, 12),
      name: c.Names[0]?.replace(/^\//, "") ?? "",
      image: c.Image,
      state: c.State,
      status: c.Status,
      ports: formatPorts(c.Ports),
      created: new Date(c.Created * 1000).toISOString(),
    }));
  }

• src/docker.ts:5-13 (schema)

  Schema definition for the ContainerInfo interface that defines the output structure returned by the list_containers tool. Specifies the fields: id, name, image, state, status, ports, and created.

  export interface ContainerInfo {
    id: string;
    name: string;
    image: string;
    state: string;
    status: string;
    ports: string;
    created: string;
  }

• src/index.ts:22-51 (registration)

  Registration of the list_containers tool with the MCP server. Defines the tool name, description, input schema using Zod (boolean 'all' parameter with default false), and the async handler that calls listContainers and formats the output as text.

  server.tool(
    "list_containers",
    "List Docker containers. Set all=true to include stopped containers.",
    {
      all: z
        .boolean()
        .optional()
        .default(false)
        .describe("Include stopped containers"),
    },
    async ({ all }) => {
      const containers = await listContainers(all);
      return {
        content: [
          {
            type: "text",
            text:
              containers.length === 0
                ? "No containers found."
                : containers
                    .map(
                      (c) =>
                        `${c.id}  ${c.name.padEnd(30)}  ${c.image.padEnd(30)}  ${c.state.padEnd(10)}  ${c.status}`,
                    )
                    .join("\n"),
          },
        ],
      };
    },
  );

• src/docker.ts:39-46 (helper)

  Helper function formatPorts used by listContainers to format Docker port mappings into a human-readable string format (e.g., '8080->80/tcp').

  function formatPorts(ports: Dockerode.Port[]): string {
    return ports
      .map((p) => {
        if (p.PublicPort) return `${p.PublicPort}->${p.PrivatePort}/${p.Type}`;
        return `${p.PrivatePort}/${p.Type}`;
      })
      .join(", ");
  }