### Development Setup for MCP Docker Server

Source: https://github.com/ofershap/mcp-server-docker/blob/main/README.md

Clone the repository, install dependencies, run tests, and build the project. These commands are essential for contributing to or modifying the MCP Docker server.

```bash
git clone https://github.com/ofershap/mcp-server-docker.git
cd mcp-server-docker
npm install
npm test
npm run build
```

--------------------------------

### Install and Configure mcp-server-docker

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Configuration for integrating mcp-server-docker with AI clients like Cursor, Claude Desktop, and VS Code. Shows how to run the server directly for testing or build from source.

```jsonc
// Cursor: .cursor/mcp.json
// Claude Desktop: claude_desktop_config.json
// VS Code: .vscode/mcp.json  (key is "mcp" > "servers")
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "mcp-docker-server"]
    }
  }
}
```

```bash
# Run the server directly for testing
npx mcp-docker-server

# Build from source
git clone https://github.com/ofershap/mcp-server-docker.git
cd mcp-server-docker
npm install
npm run build   # outputs to dist/
npm test        # runs vitest suite
```

--------------------------------

### Run MCP Docker Server

Source: https://github.com/ofershap/mcp-server-docker/blob/main/README.md

Execute the MCP Docker server using npx. This command starts the server, which then connects to your local Docker socket.

```bash
npx mcp-docker-server
```

--------------------------------

### start_container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Starts a Docker container that is currently in a stopped or exited state.

```APIDOC
## Tool: `start_container` — Start a stopped container

Starts a container that is in the stopped/exited state. Accepts either a container ID (short or full) or a container name.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to start.

### Request Example (MCP tool call)
```json
{
  "id": "start_container",
  "parameters": {
    "id": "my-nginx"
  }
}
```

### Response Example (Output text)
```text
Container my-nginx started
```
```

--------------------------------

### Start a Stopped Container with mcp-server-docker

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Starts a Docker container that is currently in a stopped or exited state. It accepts the container's ID or name. Throws an error if the container does not exist or is already running.

```typescript
import { startContainer } from "./src/docker.js";

try {
  const result: string = await startContainer("my-nginx");
  console.log(result); // "Container my-nginx started"
} catch (err) {
  // Throws if container does not exist or is already running
  console.error("Failed to start:", err);
}

// MCP tool call:
// Tool: start_container
// Input: { "id": "my-nginx" }
// Output text: "Container my-nginx started"
```

--------------------------------

### Get Docker Container Resource Usage

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Fetches a single snapshot of CPU, memory, and network I/O statistics for a running container. CPU percentage is calculated from the delta between two consecutive stat samples. Requires container ID.

```typescript
import { containerStats, ContainerStats } from "./src/docker.js";

const stats: ContainerStats = await containerStats("postgres");
console.log(stats);
// {
//   cpu_percent:    "2.45%",
//   memory_usage:   "50.0 MB",
//   memory_limit:   "1.0 GB",
//   memory_percent: "4.88%",
//   network_rx:     "1.0 KB",
//   network_tx:     "2.0 KB"
// }
```

--------------------------------

### List Docker Images

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Returns all Docker images on the host with their short ID, repository tags, human-readable size, and creation timestamp. No arguments are required.

```typescript
import { listImages, ImageInfo } from "./src/docker.js";

const images: ImageInfo[] = await listImages();
console.log(images);
// [
//   {
//     id: "abc123def456",
//     tags: ["nginx:latest"],
//     size: "135.4 MB",
//     created: "2023-11-10T10:00:00.000Z"
//   },
//   {
//     id: "def789abc012",
//     tags: ["<none>"],
//     size: "72.1 MB",
//     created: "2023-10-01T08:00:00.000Z"
//   }
// ]
```

--------------------------------

### List Docker Containers with mcp-server-docker

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Demonstrates how to list Docker containers, optionally including stopped ones. The output is formatted as a text table for AI display. This tool is useful for inspecting the current state of containers.

```typescript
import { listContainers, ContainerInfo } from "./src/docker.js";

// List only running containers (default)
const running: ContainerInfo[] = await listContainers(false);
console.log(running);
// [
//   {
//     id: "abc123def456",
//     name: "my-nginx",
//     image: "nginx:latest",
//     state: "running",
//     status: "Up 2 hours",
//     ports: "8080->80/tcp",
//     created: "2023-11-14T22:13:20.000Z"
//   }
// ]

// Include stopped containers
const all: ContainerInfo[] = await listContainers(true);
// Returns both running and exited containers

// MCP tool call (from AI assistant context):
// Tool: list_containers
// Input: { "all": true }
// Output text: "abc123def456  my-nginx                        nginx:latest                    running     Up 2 hours"
```

--------------------------------

### list_images

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Returns all Docker images on the host with their short ID, repository tags, human-readable size, and creation timestamp.

```APIDOC
## list_images

### Description
Returns all Docker images on the host with their short ID, repository tags, human-readable size, and creation timestamp.

### Parameters
This endpoint does not require any parameters.

### Request Example
```typescript
await listImages();
```

### Response
#### Success Response (200)
- **images** (array[object]) - A list of Docker images.
  - **id** (string) - The short ID of the image.
  - **tags** (array[string]) - A list of repository tags for the image.
  - **size** (string) - The human-readable size of the image.
  - **created** (string) - The timestamp when the image was created.

### Response Example
```json
[
  {
    "id": "abc123def456",
    "tags": ["nginx:latest"],
    "size": "135.4 MB",
    "created": "2023-11-10T10:00:00.000Z"
  }
]
```
```

--------------------------------

### Configure MCP Server for Cursor

Source: https://github.com/ofershap/mcp-server-docker/blob/main/README.md

Add this configuration to your `.cursor/mcp.json` file to enable the Docker MCP server within Cursor. It specifies the command and arguments to run the server.

```json
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "mcp-docker-server"]
    }
  }
}
```

--------------------------------

### Configure MCP Server for VS Code

Source: https://github.com/ofershap/mcp-server-docker/blob/main/README.md

Add this configuration to your user settings or a `.vscode/mcp.json` file to integrate the Docker MCP server with VS Code. This allows your AI assistant to manage Docker resources.

```json
{
  "mcp": {
    "servers": {
      "docker": {
        "command": "npx",
        "args": ["-y", "mcp-docker-server"]
      }
    }
  }
}
```

--------------------------------

### exec_command

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Runs an arbitrary command inside a running container and returns the combined stdout/stderr output. The command is provided as an array of strings (command + arguments).

```APIDOC
## exec_command

### Description
Runs an arbitrary command inside a running container and returns the combined stdout/stderr output. The command is provided as an array of strings (command + arguments).

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to execute the command in.
- **command** (array[string]) - Required - An array of strings representing the command and its arguments.

### Request Example
```typescript
// List files in /app
await execCommand("my-app", ["ls", "-la", "/app"]);

// Check environment variables
await execCommand("my-app", ["env"]);

// Read a config file
await execCommand("my-nginx", ["cat", "/etc/nginx/nginx.conf"]);
```

### Response
#### Success Response (200)
- **output** (string) - The combined stdout and stderr output from the executed command.

### Response Example
```json
{
  "output": "total 48\n -rw-r--r--  1 node node  312 Nov 14 22:00 package.json"
}
```
```

--------------------------------

### list_containers

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Lists Docker containers. By default, it returns only running containers. Setting `all` to `true` includes stopped and exited containers.

```APIDOC
## Tool: `list_containers` — List Docker containers

Returns all running containers (or all containers when `all: true`) with their short ID, name, image, state, status, and port mappings. The output is a formatted text table ready for display in an AI assistant's response.

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - If true, includes stopped and exited containers.

### Request Example (MCP tool call)
```json
{
  "id": "list_containers",
  "parameters": {
    "all": true
  }
}
```

### Response Example (Output text)
```text
abc123def456  my-nginx                        nginx:latest                    running     Up 2 hours
```
```

--------------------------------

### Execute Command in Docker Container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Runs an arbitrary command inside a running container and returns the combined stdout/stderr output. The command is provided as an array of strings (command + arguments). Requires container ID and command array.

```typescript
import { execCommand } from "./src/docker.js";

// List files in /app
const ls = await execCommand("my-app", ["ls", "-la", "/app"]);
console.log(ls);
// "total 48
//  drwxr-xr-x  5 node node 4096 Nov 14 22:00 .
//  drwxr-xr-x 18 root root 4096 Nov 14 21:55 ..
//  -rw-r--r--  1 node node  312 Nov 14 22:00 package.json"

// Check environment variables
const env = await execCommand("my-app", ["env"]);

// Read a config file
const config = await execCommand("my-nginx", ["cat", "/etc/nginx/nginx.conf"])
```

--------------------------------

### container_stats

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Fetches a single snapshot of CPU, memory, and network I/O statistics for a running container. CPU percentage is calculated from the delta between two consecutive stat samples returned by the Docker API.

```APIDOC
## container_stats

### Description
Fetches a single snapshot of CPU, memory, and network I/O statistics for a running container.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to get statistics for.

### Request Example
```typescript
await containerStats("postgres");
```

### Response
#### Success Response (200)
- **cpu_percent** (string) - The current CPU utilization percentage.
- **memory_usage** (string) - The current memory usage.
- **memory_limit** (string) - The memory limit for the container.
- **memory_percent** (string) - The current memory utilization percentage.
- **network_rx** (string) - The total network traffic received.
- **network_tx** (string) - The total network traffic transmitted.

### Response Example
```json
{
  "cpu_percent": "2.45%",
  "memory_usage": "50.0 MB",
  "memory_limit": "1.0 GB",
  "memory_percent": "4.88%",
  "network_rx": "1.0 KB",
  "network_tx": "2.0 KB"
}
```
```

--------------------------------

### Core Docker Functions

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Provides programmatic access to Docker functionalities. These functions are designed to be imported and used directly within TypeScript projects, offering a higher-level API over dockerode. All functions are expected to throw errors on Docker API failures, so they should be wrapped in try/catch blocks.

```APIDOC
## Core Docker Functions (Internal API — `src/docker.ts`)

The internal TypeScript functions used by all MCP tools, directly callable when embedding `mcp-server-docker` logic or writing tests.

```typescript
import Dockerode from "dockerode";
import {
  listContainers,   // (all: boolean) => Promise<ContainerInfo[]>
  containerLogs,    // (id: string, tail: number) => Promise<string>
  startContainer,   // (id: string) => Promise<string>
  stopContainer,    // (id: string) => Promise<string>
  restartContainer, // (id: string) => Promise<string>
  removeContainer,  // (id: string, force: boolean) => Promise<string>
  execCommand,      // (id: string, command: string[]) => Promise<string>
  containerStats,   // (id: string) => Promise<ContainerStats>
  listImages,       // () => Promise<ImageInfo[]>
  removeImage,      // (id: string, force: boolean) => Promise<string>
} from "./src/docker.js";

// All functions throw on Docker API errors — wrap in try/catch
async function debugContainer(name: string) {
  try {
    // 1. Check if container is running
    const containers = await listContainers(true);
    const target = containers.find((c) => c.name === name);
    if (!target) throw new Error(`Container "${name}" not found");

    // 2. Check resource pressure
    if (target.state === "running") {
      const stats = await containerStats(name);
      console.log(`CPU: ${stats.cpu_percent}, Mem: ${stats.memory_percent}`);
    }

    // 3. Tail recent logs
    const logs = await containerLogs(name, 200);
    console.log(logs);

    // 4. Inspect filesystem inside container
    const files = await execCommand(name, ["ls", "-la", "/var/log"]);
    console.log(files);
  } catch (err) {
    console.error("Debug failed:", err);
  }
}
```
```

--------------------------------

### Fetch Container Logs with mcp-server-docker

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Retrieves a specified number of recent log lines (stdout/stderr) from a Docker container. Binary log control characters are stripped for clean UTF-8 output. Useful for debugging.

```typescript
import { containerLogs } from "./src/docker.js";

// Get last 50 lines from a container by name
const logs: string = await containerLogs("my-nginx", 50);
console.log(logs);
// "2023/11/14 22:15:01 [notice] 1#1: nginx/1.25.3
//  2023/11/14 22:15:01 [notice] 1#1: start worker processes
//  172.17.0.1 - - [14/Nov/2023:22:15:10 +0000] \"GET / HTTP/1.1\" 200 615"

// Get full logs (large tail value)
const allLogs = await containerLogs("abc123def456", 1000);

// MCP tool call:
// Tool: container_logs
// Input: { "id": "my-nginx", "tail": 50 }
// Output text: <raw log lines>
```

--------------------------------

### restart_container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Stops and immediately restarts a running or stopped container. Useful for applying configuration changes or recovering from transient failures.

```APIDOC
## restart_container

### Description
Stops and immediately restarts a running or stopped container. Useful for applying configuration changes or recovering from transient failures.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to restart.

### Request Example
```typescript
await restartContainer("api-server");
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the container was restarted.

### Response Example
```json
{
  "message": "Container api-server restarted"
}
```
```

--------------------------------

### container_logs

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Retrieves logs from a specified container. You can control the number of log lines returned.

```APIDOC
## Tool: `container_logs` — Fetch container logs

Retrieves the last N lines (default 100) of stdout/stderr from a container. Docker's binary log control characters are stripped, returning clean UTF-8 text.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container.
#### Query Parameters
- **tail** (number) - Optional - The number of lines to return. Defaults to 100.

### Request Example (MCP tool call)
```json
{
  "id": "container_logs",
  "parameters": {
    "id": "my-nginx",
    "tail": 50
  }
}
```

### Response Example (Output text)
```text
2023/11/14 22:15:01 [notice] 1#1: nginx/1.25.3
2023/11/14 22:15:01 [notice] 1#1: start worker processes
172.17.0.1 - - [14/Nov/2023:22:15:10 +0000] "GET / HTTP/1.1" 200 615
```
```

--------------------------------

### Restart Docker Container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Stops and immediately restarts a specified container. Useful for applying configuration changes or recovering from transient failures. Requires the container ID.

```typescript
import { restartContainer } from "./src/docker.js";

try {
  const result: string = await restartContainer("api-server");
  console.log(result); // "Container api-server restarted"
} catch (err) {
  console.error("Failed to restart:", err);
}
```

--------------------------------

### Import Core Docker Functions

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Imports various Docker management functions from the internal docker.js module. All functions are designed to throw errors on Docker API failures, necessitating try/catch blocks for robust error handling.

```typescript
import Dockerode from "dockerode";
import {
  listContainers,
  containerLogs,
  startContainer,
  stopContainer,
  restartContainer,
  removeContainer,
  execCommand,
  containerStats,
  listImages,
  removeImage,
} from "./src/docker.js";
```

--------------------------------

### Stop a Running Container with mcp-server-docker

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Gracefully stops a running Docker container by sending a SIGTERM signal, followed by SIGKILL if necessary. Handles potential errors during the stop process.

```typescript
import { stopContainer } from "./src/docker.js";

try {
  const result: string = await stopContainer("my-nginx");
  console.log(result); // "Container my-nginx stopped"
} catch (err) {
  console.error("Failed to stop:", err);
}

// MCP tool call:
// Tool: stop_container
// Input: { "id": "abc123def456" }
// Output text: "Container abc123def456 stopped"
```

--------------------------------

### stop_container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Stops a running Docker container gracefully by sending a SIGTERM signal.

```APIDOC
## Tool: `stop_container` — Stop a running container

Sends a SIGTERM (then SIGKILL after timeout) to a running container, gracefully shutting it down.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to stop.

### Request Example (MCP tool call)
```json
{
  "id": "stop_container",
  "parameters": {
    "id": "abc123def456"
  }
}
```

### Response Example (Output text)
```text
Container abc123def456 stopped
```
```

--------------------------------

### Remove Docker Container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Removes a stopped container. Use `force: true` to stop and remove a running container atomically. Requires the container ID and a boolean for force removal.

```typescript
import { removeContainer } from "./src/docker.js";

// Remove a stopped container
const result1 = await removeContainer("old-container", false);
console.log(result1); // "Container old-container removed"

// Force-remove a running container (stop + remove atomically)
const result2 = await removeContainer("stuck-container", true);
console.log(result2); // "Container stuck-container removed"
```

--------------------------------

### Debug Container Functionality

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

A function to debug a specified container by checking its status, resource usage, recent logs, and filesystem contents. It includes error handling for cases where the container is not found or other Docker API errors occur.

```typescript
async function debugContainer(name: string) {
  try {
    // 1. Check if container is running
    const containers = await listContainers(true);
    const target = containers.find((c) => c.name === name);
    if (!target) throw new Error(`Container "${name}" not found`);

    // 2. Check resource pressure
    if (target.state === "running") {
      const stats = await containerStats(name);
      console.log(`CPU: ${stats.cpu_percent}, Mem: ${stats.memory_percent}`);
    }

    // 3. Tail recent logs
    const logs = await containerLogs(name, 200);
    console.log(logs);

    // 4. Inspect filesystem inside container
    const files = await execCommand(name, ["ls", "-la", "/var/log"]);
    console.log(files);
  } catch (err) {
    console.error("Debug failed:", err);
  }
}
```

--------------------------------

### remove_container

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Removes a stopped container. Pass `force: true` to stop and remove a running container in a single operation.

```APIDOC
## remove_container

### Description
Removes a stopped container. Pass `force: true` to stop and remove a running container in a single operation.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the container to remove.
#### Query Parameters
- **force** (boolean) - Optional - If true, stops and removes a running container.

### Request Example
```typescript
// Remove a stopped container
await removeContainer("old-container", false);

// Force-remove a running container (stop + remove atomically)
await removeContainer("stuck-container", true);
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the container was removed.

### Response Example
```json
{
  "message": "Container old-container removed"
}
```
```

--------------------------------

### Remove Docker Image

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Removes an image by ID or tag. Use `force: true` to remove an image that is in use by a stopped container. Requires image identifier and a boolean for force removal.

```typescript
import { removeImage } from "./src/docker.js";

// Remove by tag
const result1 = await removeImage("nginx:old", false);
console.log(result1); // "Image nginx:old removed"

// Force-remove an image used by a stopped container
const result2 = await removeImage("abc123def456", true);
console.log(result2); // "Image abc123def456 removed"
```

--------------------------------

### remove_image

Source: https://context7.com/ofershap/mcp-server-docker/llms.txt

Removes an image by ID or tag. Use `force: true` to remove an image that is in use by a stopped container.

```APIDOC
## remove_image

### Description
Removes an image by ID or tag. Use `force: true` to remove an image that is in use by a stopped container.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or tag of the image to remove.
#### Query Parameters
- **force** (boolean) - Optional - If true, removes an image even if it's used by a stopped container.

### Request Example
```typescript
// Remove by tag
await removeImage("nginx:old", false);

// Force-remove an image used by a stopped container
await removeImage("abc123def456", true);
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the image was removed.

### Response Example
```json
{
  "message": "Image nginx:old removed"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.