Skip to main content
Glama
Sign In
docker-mcp-server

docker-mcp-server

by L337-org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

container_stats

Read-only

Get a point-in-time resource usage snapshot for a container, returning raw engine stats. Compute CPU percent from delta data or use one_shot for faster memory and PID stats without CPU calculation.

Instructions

Get one point-in-time resource-usage snapshot for a container (non-streaming).

Returns the raw engine stats payload; CPU percent must be computed from the delta between cpu_stats and precpu_stats. By default the daemon collects two cycles before answering, which is what fills precpu_stats - so the call takes about a second. one_shot=True returns after a single collection instead, leaving precpu_stats zeroed and CPU percent uncomputable; use it when only memory_stats/pids_stats matter. For a pre-computed human-readable summary prefer the docker-stats://{id_or_name} resource; for a process listing use container_top.

Args: one_shot: Skip the second collection cycle for a faster answer, at the cost of an empty precpu_stats (so no CPU percent); needs daemon API v1.41+

Returns: dict: Engine stats payload (read, cpu_stats, precpu_stats, memory_stats, networks, pids_stats, ...)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id_or_name": "<id_or_name>"
    },
    "name": "container_stats"
  }
}

Input Schema

NameRequiredDescriptionDefault
one_shotNo
id_or_nameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.2.6
    • addedInput schema / properties / one_shot
      Added value: +{
+  "default": false,
+  "type": "boolean"
+}
  2. First observedv1.9.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description reveals critical behavioral nuances: the default two-cycle collection and ~1s latency, the impact of one_shot on precpu_stats and CPU computation, and the daemon API v1.41+ requirement. This gives the agent full awareness of side effects and performance, far exceeding the annotation's simple read-only flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence contributes unique information: purpose, return format, CPU delta explanation, timing, one_shot behavior, and alternatives. The Args and Returns sections are cleanly structured and avoid redundancy. The main paragraph is front-loaded with the core purpose and then layers trade-offs and context, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and only two parameters, this description is remarkably complete. It explains how to interpret the raw payload (CPU percent computation), the timing expectation, the one_shot flag's consequences, API version requirements, and directs to alternative tools. An agent has everything needed to call it correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well for one_shot, explaining its purpose, impact, and version requirement. The id_or_name parameter is not explicitly described, but its meaning is self-evident from the tool name and context. The description adds semantic value for the non-obvious parameter while relying on naming for the obvious one.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb-resource pair: 'Get one point-in-time resource-usage snapshot for a container (non-streaming).' It clearly distinguishes this tool from siblings by naming alternatives (container_top for process listing, docker-stats resource for a pre-computed summary) and specifying the non-streaming nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Guidance is explicit and actionable. It states when to prefer the docker-stats resource, when to use container_top, and explains the one_shot trade-off for scenarios where only memory/pids matter. This goes beyond a simple 'use for stats' and directly tells the agent when to choose an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools