# Docker MCP Server

基于MCP标准协议的Docker操作工具，支持标准的Docker CLI命令和Docker Compose操作。

## MCP 协议支持

此服务器完全符合MCP（Model Context Protocol）标准，包括：

- 支持MCP协议版本：2024-11-05
- 初始化和生命周期管理
- 标准工具接口（tools/list, tools/call）
- 正确的错误处理（带有isError字段）
- 符合JSON-RPC 2.0消息格式

## 功能特性

### 基本容器操作

* `list_containers` - 列出所有Docker容器
* `list_images` - 列出所有Docker镜像
* `run_container` - 运行一个Docker容器，支持多种参数配置
* `stop_container` - 停止一个Docker容器
* `remove_container` - 移除一个Docker容器
* `pull_image` - 拉取一个Docker镜像

### Docker Compose操作

* `compose_up` - 启动Docker Compose服务
* `compose_down` - 停止并移除Docker Compose服务
* `compose_ps` - 列出Docker Compose服务
* `compose_logs` - 查看Docker Compose服务的日志
* `compose_build` - 构建Docker Compose服务

> **特别说明**: 支持Docker Compose的新老版本命令，自动在`docker compose`(新版)和`docker-compose`(旧版)之间切换。服务器会优先尝试新版命令格式，如失败则自动尝试使用旧版命令，以提供最大兼容性。

### 高级容器管理

* `inspect_container` - 展示容器的详细信息
* `container_logs` - 获取容器的日志
* `exec_container` - 在运行中的容器中执行命令
* `container_stats` - 显示容器资源使用情况统计

### 镜像管理

* `build_image` - 从Dockerfile构建镜像
* `prune_images` - 移除未使用的镜像

### 网络管理

* `list_networks` - 列出所有Docker网络
* `create_network` - 创建一个新的Docker网络
* `remove_network` - 移除一个Docker网络
* `network_connect` - 将容器连接到网络

### 卷管理

* `list_volumes` - 列出所有Docker卷
* `create_volume` - 创建一个Docker卷
* `remove_volume` - 移除一个Docker卷

### 系统信息

* `system_info` - 显示系统级信息
* `system_df` - 显示Docker磁盘使用情况

### 安全检查

* `security_scan` - 扫描Docker镜像中的漏洞（需要安装额外工具如trivy）

## 使用方法

1. 确保安装了NodeJS和Docker
2. 克隆仓库并安装依赖
   ```
   git clone https://github.com/yourusername/docker-mcp.git
   cd docker-mcp
   npm install
   ```
3. 构建项目
   ```
   npm run build
   ```
4. 运行服务器
   ```
   npm start
   ```

## 与MCP客户端集成

任何支持MCP协议的客户端都可以与此服务器交互，例如：

1. 初始化连接：`initialize`
2. 获取可用工具列表：`tools/list`
3. 调用工具：`tools/call` 使用指定的工具名称和参数

## Features

- List Docker containers
- List Docker images
- Run Docker containers
- Stop running containers
- Remove containers
- Pull Docker images from registries
- Docker Compose operations (up, down, ps, logs, build)
- **Compatibility with both new and legacy Docker Compose versions**

## Installation

### Prerequisites

- Node.js 18 or higher
- Docker installed and running on your system
- Docker Compose installed (for Compose operations)
  - Both `docker compose` (V2, integrated) and `docker-compose` (V1, standalone) are supported

### Install from npm

```bash
npm install -g docker-mcp-server
```

### Install from source

1. Clone this repository
2. Install dependencies:

```bash
cd docker-mcp
npm install
```

3. Build the project:

```bash
npm run build
```

## Usage

### Running the server

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

Or if installed from source:

```bash
npm start
```

### Configuring with Claude

You can use the included installation script to automatically configure the Docker MCP server with Claude:

```bash
npm run install-config
```

This script will:
1. Detect your Claude installations (Desktop and/or VSCode)
2. Update the configuration files to include the Docker MCP server
3. Set up the correct paths for your system

#### Manual Configuration

If you prefer to configure manually, you need to add the Docker MCP server to your MCP settings configuration file:

##### For Claude Desktop App (macOS)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "docker-mcp": {
      "command": "node",
      "args": ["/path/to/docker-mcp/dist/index.js"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

##### For Claude in VSCode

Edit `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "docker-mcp": {
      "command": "node",
      "args": ["/path/to/docker-mcp/dist/index.js"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**Note:** After configuring the Docker MCP server in VS Code, you may need to restart VS Code for the changes to take effect in Cline. If you encounter issues with the Docker MCP server not being recognized or working properly in Cline, try restarting VS Code.

## MCP Compliance

This server implements the Model Context Protocol (MCP) standard and supports:

- MCP protocol version: 2024-11-05
- Initialization and lifecycle management
- Standard tools interface with `tools/list` and `tools/call` methods
- Proper error handling following MCP conventions
- JSON-RPC 2.0 message format

## Available Tools

### Docker Container Tools

#### list_containers

List all Docker containers.

Parameters:
- `all` (boolean, optional): Show all containers (default shows just running)

#### list_images

List all Docker images.

#### run_container

Run a Docker container.

Parameters:
- `image` (string, required): Docker image to run
- `name` (string, optional): Name for the container
- `detach` (boolean, optional): Run container in background
- `ports` (array of strings, optional): Port mappings (e.g. ["8080:80"])
- `volumes` (array of strings, optional): Volume mappings (e.g. ["/host/path:/container/path"])
- `env` (array of strings, optional): Environment variables (e.g. ["KEY=value"])
- `command` (string, optional): Command to run in the container

#### stop_container

Stop a running Docker container.

Parameters:
- `container` (string, required): Container ID or name

#### remove_container

Remove a Docker container.

Parameters:
- `container` (string, required): Container ID or name
- `force` (boolean, optional): Force removal of running container

#### pull_image

Pull a Docker image from a registry.

Parameters:
- `image` (string, required): Image name (e.g. "nginx:latest")

### Docker Compose Tools

> All Docker Compose tools support both `docker compose` (V2) and `docker-compose` (V1) commands, with automatic fallback from new to legacy format if needed.

#### compose_up

Start Docker Compose services.

Parameters:
- `file` (string, optional): Path to docker-compose.yml file
- `projectName` (string, optional): Specify project name
- `services` (array of strings, optional): Services to start (default: all services)
- `detach` (boolean, optional): Run in background
- `build` (boolean, optional): Build images before starting containers
- `removeOrphans` (boolean, optional): Remove containers for services not defined in the Compose file

#### compose_down

Stop and remove Docker Compose services.

Parameters:
- `file` (string, optional): Path to docker-compose.yml file
- `projectName` (string, optional): Specify project name
- `volumes` (boolean, optional): Remove named volumes declared in the volumes section
- `removeOrphans` (boolean, optional): Remove containers for services not defined in the Compose file

#### compose_ps

List Docker Compose services.

Parameters:
- `file` (string, optional): Path to docker-compose.yml file
- `projectName` (string, optional): Specify project name
- `services` (array of strings, optional): Services to show (default: all services)

#### compose_logs

View Docker Compose service logs.

Parameters:
- `file` (string, optional): Path to docker-compose.yml file
- `projectName` (string, optional): Specify project name
- `services` (array of strings, optional): Services to show logs for (default: all services)
- `follow` (boolean, optional): Follow log output
- `tail` (string, optional): Number of lines to show from the end of the logs (e.g. "100")

#### compose_build

Build Docker Compose services.

Parameters:
- `file` (string, optional): Path to docker-compose.yml file
- `projectName` (string, optional): Specify project name
- `services` (array of strings, optional): Services to build (default: all services)
- `noCache` (boolean, optional): Do not use cache when building the image
- `pull` (boolean, optional): Always attempt to pull a newer version of the image

### Advanced Container Management Tools

#### inspect_container

Show detailed information about a container.

Parameters:
- `container` (string, required): Container ID or name
- `format` (string, optional): Format the output using a Go template

#### container_logs

Fetch the logs of a container.

Parameters:
- `container` (string, required): Container ID or name
- `tail` (string, optional): Number of lines to show from the end of the logs (e.g. "100")
- `since` (string, optional): Show logs since timestamp (e.g. "2021-01-02T13:23:37") or relative (e.g. "42m" for 42 minutes)
- `until` (string, optional): Show logs before timestamp (e.g. "2021-01-02T13:23:37") or relative (e.g. "42m" for 42 minutes)
- `timestamps` (boolean, optional): Show timestamps

#### exec_container

Execute a command in a running container.

Parameters:
- `container` (string, required): Container ID or name
- `command` (string, required): Command to execute
- `interactive` (boolean, optional): Keep STDIN open even if not attached

#### container_stats

Display a live stream of container resource usage statistics.

Parameters:
- `container` (string, required): Container ID or name
- `noStream` (boolean, optional): Disable streaming stats and only pull the first result

### Image Management Tools

#### build_image

Build an image from a Dockerfile.

Parameters:
- `dockerfile` (string, optional): Path to Dockerfile
- `tag` (string, required): Name and optionally a tag in the name:tag format
- `context` (string, required): Path to the build context
- `buildArgs` (object, optional): Build-time variables
- `noCache` (boolean, optional): Do not use cache when building the image
- `pull` (boolean, optional): Always attempt to pull a newer version of the image

#### prune_images

Remove unused images.

Parameters:
- `all` (boolean, optional): Remove all unused images, not just dangling ones
- `filter` (string, optional): Provide filter values (e.g. "until=24h")

### Network Management Tools

#### list_networks

List all Docker networks.

#### create_network

Create a new Docker network.

Parameters:
- `name` (string, required): Network name
- `driver` (string, optional): Driver to manage the network (default "bridge")
- `subnet` (string, optional): Subnet in CIDR format (e.g. "172.30.0.0/16")
- `gateway` (string, optional): Gateway for the subnet
- `internal` (boolean, optional): Restrict external access to the network

#### remove_network

Remove a Docker network.

Parameters:
- `name` (string, required): Network name or ID

#### network_connect

Connect a container to a network.

Parameters:
- `network` (string, required): Network name or ID
- `container` (string, required): Container ID or name
- `alias` (array of strings, optional): Add network-scoped alias for the container

### Volume Management Tools

#### list_volumes

List all Docker volumes.

#### create_volume

Create a Docker volume.

Parameters:
- `name` (string, required): Volume name
- `driver` (string, optional): Volume driver name (default "local")
- `labels` (object, optional): Labels to set on the volume

#### remove_volume

Remove a Docker volume.

Parameters:
- `name` (string, required): Volume name

### System Information Tools

#### system_info

Display system-wide information.

Parameters:
- `format` (string, optional): Format the output using a Go template

#### system_df

Show Docker disk usage.

Parameters:
- `verbose` (boolean, optional): Show detailed information on space usage

### Security Tools

#### security_scan

Scan a Docker image for vulnerabilities.

Parameters:
- `image` (string, required): Image to scan (e.g. "nginx:latest")
- `verbose` (boolean, optional): Show detailed vulnerability information

**Note:** Security scanning requires external tools like trivy to be installed on your system.

## License

MIT