mcp-server-docker

Instructions

Implementation Reference

• src/docker.ts:136-179 (handler)

  The containerStats function is the core handler that executes the tool logic. It retrieves Docker container stats via dockerode, calculates CPU percentage from cpu_stats, computes memory usage/limit/percentage, and aggregates network RX/TX bytes across all interfaces, returning a formatted ContainerStats object.

  export async function containerStats(id: string): Promise<ContainerStats> {
    const container = docker.getContainer(id);
    const stats = (await container.stats({
      stream: false,
    })) as {
      cpu_stats: CpuStats;
      precpu_stats: CpuStats;
      memory_stats: MemoryStats;
      networks?: NetworkStats;
    };
  
    const cpuStats = stats.cpu_stats;
    const precpuStats = stats.precpu_stats;
    const cpuDelta =
      cpuStats.cpu_usage.total_usage - precpuStats.cpu_usage.total_usage;
    const systemDelta = cpuStats.system_cpu_usage - precpuStats.system_cpu_usage;
    const cpuCount = cpuStats.cpu_usage.percpu_usage?.length ?? 1;
    const cpuPercent =
      systemDelta > 0
        ? ((cpuDelta / systemDelta) * cpuCount * 100).toFixed(2)
        : "0.00";
  
    const memUsage = stats.memory_stats.usage ?? 0;
    const memLimit = stats.memory_stats.limit ?? 0;
    const memPercent =
      memLimit > 0 ? ((memUsage / memLimit) * 100).toFixed(2) : "0.00";
  
    const networks = stats.networks ?? {};
    let rxBytes = 0;
    let txBytes = 0;
    for (const iface of Object.values(networks)) {
      rxBytes += iface.rx_bytes ?? 0;
      txBytes += iface.tx_bytes ?? 0;
    }
  
    return {
      cpu_percent: `${cpuPercent}%`,
      memory_usage: formatBytes(memUsage),
      memory_limit: formatBytes(memLimit),
      memory_percent: `${memPercent}%`,
      network_rx: formatBytes(rxBytes),
      network_tx: formatBytes(txBytes),
    };
  }

• src/docker.ts:15-22 (schema)

  The ContainerStats interface defines the output schema with typed fields: cpu_percent, memory_usage, memory_limit, memory_percent, network_rx, and network_tx (all strings with formatted values).

  export interface ContainerStats {
    cpu_percent: string;
    memory_usage: string;
    memory_limit: string;
    memory_percent: string;
    network_rx: string;
    network_tx: string;
  }

• src/index.ts:134-153 (registration)

  Registration of the 'container_stats' tool using server.tool() with a zod schema defining 'id' parameter (string, required). The handler calls containerStats(id) and formats the result into a human-readable text output showing CPU, memory, and network statistics.

  server.tool(
    "container_stats",
    "Get CPU, memory, and network stats for a running Docker container.",
    { id: z.string().describe("Container ID or name") },
    async ({ id }) => {
      const stats = await containerStats(id);
      return {
        content: [
          {
            type: "text",
            text: [
              `CPU:     ${stats.cpu_percent}`,
              `Memory:  ${stats.memory_usage} / ${stats.memory_limit} (${stats.memory_percent})`,
              `Network: ↓ ${stats.network_rx}  ↑ ${stats.network_tx}`,
            ].join("\n"),
          },
        ],
      };
    },
  );