Docker MCP với Gemini CLI

Gemini CLI là công cụ dòng lệnh chính chủ của Google để chạy Gemini như một coding agent, hỗ trợ MCP (Model Context Protocol) qua file cấu hình riêng khác với format của Claude Code. Nếu bạn đã quen Docker MCP trên Claude Code hoặc Cursor, phần lớn kiến thức về tool và use case vẫn dùng lại được — điểm khác biệt chính nằm ở cách khai báo server và một số hành vi tool-calling đặc trưng của model Gemini.

Bài này đi qua cách cài Docker MCP cho Gemini CLI, cách đọc log/health container, một ví dụ thực tế sửa multi-stage build bị lỗi, và cuối cùng so sánh trực tiếp hành vi Docker MCP giữa Gemini CLI và Claude Code — để bạn biết nên kỳ vọng gì khi chuyển đổi giữa hai công cụ.

Cài Đặt Và Kết Nối Docker MCP Với Gemini CLI

Gemini CLI đọc cấu hình MCP từ file .gemini/settings.json ở root project, hoặc file settings global tại ~/.gemini/settings.json. Trước khi cấu hình, đảm bảo bạn đã đăng nhập Gemini CLI và Docker daemon đang chạy:

gemini auth status
docker info --format '{{.ServerVersion}}'

Thêm block mcpServers vào .gemini/settings.json:

{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Nếu bạn dùng MCP server tự build chạy trong container riêng (thay vì Docker MCP Toolkit có sẵn), cấu hình tương tự nhưng cần mount socket:

{
  "mcpServers": {
    "docker-custom": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "my-org/docker-mcp-server:latest"
      ]
    }
  }
}

Sau khi lưu, chạy Gemini CLI trong project và kiểm tra MCP server đã load:

gemini

Trong session, gõ lệnh kiểm tra MCP:

/mcp

Gemini CLI sẽ hiện danh sách server kèm trạng thái kết nối và tool được expose. Nếu server không kết nối được, các nguyên nhân thường gặp: Docker daemon chưa chạy, đường dẫn docker binary không nằm trong PATH mà Gemini CLI process nhìn thấy (đặc biệt hay gặp trên máy có nhiều phiên bản Docker cài qua Homebrew lẫn Docker Desktop), hoặc file JSON bị sai cú pháp.

Xác nhận quyền hạn trước khi chạy task thật

Trước khi giao task có side-effect, hỏi một prompt đọc-only để xác nhận agent đã kết nối đúng:

List toàn bộ container đang chạy, kèm image và port mapping của
từng container.

Nếu kết quả đúng với thực tế bạn biết trên máy, coi như kết nối ổn định để chuyển sang các task debug thật.

Mẹo: Nếu Gemini CLI báo lỗi "command not found: docker" dù bạn chạy docker bình thường ở terminal, kiểm tra lại PATH trong shell mà Gemini CLI thực sự dùng — trên macOS với Docker Desktop cài qua GUI, đôi khi cần khai báo full path /usr/local/bin/docker hoặc /Applications/Docker.app/Contents/Resources/bin/docker trong field command.

Đọc Log Container Và Trạng Thái Health Từ Gemini CLI

Sau khi kết nối ổn định, việc dùng thường xuyên nhất là đọc log và health status để triage nhanh vấn đề mà không cần mở terminal riêng chạy docker logs hay docker inspect.

Prompt đọc log cơ bản, luôn giới hạn số dòng để tránh tràn context:

Lấy 100 dòng log cuối của container "api-gateway", chỉ hiển thị các
dòng có chứa "ERROR" hoặc "WARN", kèm timestamp.

Với container có định nghĩa HEALTHCHECK trong Dockerfile hoặc compose file, agent có thể đọc trực tiếp trạng thái health thay vì bạn tự đoán qua log:

Kiểm tra health status hiện tại của toàn bộ container trong project.
Với container nào đang "unhealthy", lấy log của health check gần
nhất (thường nằm trong phần State.Health.Log khi inspect container)
và giải thích vì sao health check đang fail.

Đây là một chi tiết nhiều dev bỏ qua khi debug tay: Docker lưu lại lịch sử vài lần health check gần nhất trong State.Health.Log, chứa exact command đã chạy, exit code, và output — thông tin này thường chính xác hơn nhiều so với việc chỉ nhìn log application chung.

So sánh log giữa nhiều container cùng lúc

Một use case mạnh của MCP so với CLI tay: agent đọc và so sánh log của nhiều container trong một lượt, thứ mà làm tay sẽ phải mở nhiều terminal tab:

So sánh log của 3 container "api", "worker", "scheduler" trong 5 phút
gần nhất, tìm timestamp mà cả 3 đều có warning hoặc error xuất hiện
gần nhau (trong vòng 10 giây) — đây có thể là dấu hiệu một sự cố
lan truyền giữa các service (ví dụ database bị chậm ảnh hưởng cả 3).

Đây chính là kiểu correlation (tương quan sự kiện) mà một agent với MCP tool xử lý nhanh hơn con người rất nhiều, vì nó đọc và so khớp timestamp giữa nhiều nguồn log đồng thời trong bộ nhớ, không cần bạn tự copy-paste log qua lại giữa các cửa sổ.

Mẹo: Khi hỏi về health check, luôn yêu cầu agent trích dẫn nguyên văn command health check đã định nghĩa (từ Dockerfile hoặc compose) — nhiều health check fail không phải vì service lỗi, mà vì command check (ví dụ curl localhost:8080/health) chạy sai vì thiếu curl trong base image alpine.

Ví Dụ Thực Tế: Sửa Multi-Stage Build Bị Lỗi Với Gemini CLI

Multi-stage build (build nhiều giai đoạn, mỗi stage build ra một phần rồi copy phần cần thiết sang stage sau) là kỹ thuật tối ưu size image rất phổ biến, nhưng cũng dễ gây lỗi khó hiểu vì file/artifact không được copy đúng giữa các stage.

Giả sử bạn có Dockerfile sau, build fail ở stage runtime với lỗi khó hiểu:

FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o /out/server .

FROM alpine:3.19
COPY --from=builder /app/server /usr/local/bin/server
CMD ["/usr/local/bin/server"]

Prompt yêu cầu Gemini CLI chẩn đoán:

Build Dockerfile này đang fail ở stage thứ 2 với lỗi liên quan tới
COPY --from=builder. Hãy đọc kỹ Dockerfile (tôi paste nội dung ở
trên), xác định chính xác vì sao đường dẫn COPY không tìm thấy file,
và đưa ra bản sửa.

Nguyên nhân ở đây (bug rất phổ biến với multi-stage build): stage builder build ra file tại /out/server, nhưng stage runtime lại COPY từ /app/server — sai đường dẫn hoàn toàn. Agent cần đọc kỹ từng dòng RUN/COPY để phát hiện đúng chỗ lệch, không chỉ đoán chung "thiếu file".

Bản sửa đúng:

FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o /out/server .

FROM alpine:3.19
COPY --from=builder /out/server /usr/local/bin/server
CMD ["/usr/local/bin/server"]

Sau khi sửa, luôn yêu cầu agent verify lại bằng build thật, không chỉ tin vào phân tích tĩnh:

Build lại image với Dockerfile đã sửa, tag "server:fixed", xác nhận
build pass, rồi chạy thử container này và kiểm tra process
"/usr/local/bin/server" có start thành công không (đọc log/exit code
sau vài giây chạy).

Một lỗi multi-stage build khác thường gặp: thiếu runtime dependency

Một pattern lỗi khác agent cần biết để nhận diện: binary build ra ở stage builder cần shared library (ví dụ glibc) nhưng stage runtime dùng alpine (dùng musl libc, không tương thích hoàn toàn với binary build sẵn cho glibc), dẫn tới lỗi exec format error hoặc not found khi chạy binary dù file rõ ràng tồn tại trong image. Đây là lý do với Go, nên build với CGO_ENABLED=0 để có static binary không phụ thuộc libc, hoặc dùng base image debian:slim thay vì alpine nếu binary cần glibc.

Mẹo: Khi debug multi-stage build lỗi, luôn yêu cầu agent liệt kê rõ từng stage, tên stage (AS builder), và đường dẫn file ở mỗi bước COPY --from= — vẽ ra "bản đồ" luồng file giữa các stage giúp phát hiện sai lệch đường dẫn nhanh hơn nhiều so với đọc Dockerfile tuyến tính từ trên xuống.

So Sánh Hành Vi Docker MCP Giữa Gemini CLI Và Claude Code

Nếu team bạn dùng cả hai công cụ (một số dev quen Claude Code, số khác quen Gemini CLI), nên biết trước một số khác biệt hành vi để tránh bất ngờ khi chuyển đổi.

Điểm chung quan trọng nhất: bất kể dùng công cụ nào, nguyên tắc an toàn với Docker socket (đã nói ở bài đầu module) không thay đổi — luôn giới hạn quyền exec_in_container/prune/remove_image cho session có giám sát, bất kể agent đứng sau là Claude hay Gemini.

Một khác biệt thực tế mình quan sát được khi test cả hai trên cùng task debug crash loop: cả hai đều gọi đúng chuỗi tool list_containers → inspect_container → get_logs, nhưng Gemini CLI đôi khi cần prompt nêu rõ hơn thứ tự bước (dạng danh sách số 1-2-3-4) để đảm bảo không bỏ sót bước inspect_container lấy exit code, trong khi Claude Code có xu hướng tự suy ra thứ tự hợp lý hơn từ một câu mô tả mục tiêu ngắn.

Mẹo: Nếu team dùng cả hai công cụ, hãy chuẩn hoá bộ prompt debug Docker MCP dùng chung ở dạng liệt kê từng bước rõ ràng (không phụ thuộc vào khả năng "tự suy luận thứ tự" của một model cụ thể) — cách viết này hoạt động tốt và ổn định trên cả Claude Code và Gemini CLI.

Tips

Docker MCP hoạt động tốt trên Gemini CLI với điều kiện bạn quen với format cấu hình riêng của nó và viết prompt đủ rõ ràng về thứ tự các bước cần agent thực hiện. Một vài điểm chốt lại:

• Luôn kiểm tra PATH của Docker binary nếu Gemini CLI báo lỗi command not found, đặc biệt trên máy có nhiều cách cài Docker khác nhau.
• Giới hạn số dòng log (tail) rõ ràng trong mọi prompt đọc log, tránh tràn context window với log dài.
• Với multi-stage build lỗi, luôn yêu cầu agent vẽ rõ "bản đồ" đường dẫn file giữa các stage trước khi kết luận nguyên nhân.
• Verify mọi kết luận về build fix bằng build thật, không chỉ tin phân tích tĩnh Dockerfile.
• Nếu dùng đa công cụ AI trong team, chuẩn hoá prompt debug ở dạng liệt kê bước rõ ràng để hành vi nhất quán giữa các model backend.

Mẹo: Viết sẵn một bộ prompt debug Docker chuẩn (crash loop, build fail, health check fail) dạng template có chỗ điền tên container/service, dùng chung cho cả Gemini CLI và các công cụ AI khác trong team — giảm phụ thuộc vào việc một cá nhân "nhớ" cách hỏi đúng.