·

GitLab MCP với Claude Code CLI and VS Code

Cài đặt GitLab MCP trong Claude Code CLI and VS Code để AI agent có thể quản lý repository, merge request và pipeline CI/CD ngay trong trình soạn thảo.

Claude Code là một trong những coding agent CLI được dùng nhiều nhất hiện nay, và việc gắn GitLab MCP vào Claude Code giúp bạn ra lệnh trực tiếp bằng ngôn ngữ tự nhiên để xử lý merge request, issue, pipeline — mà không cần rời terminal. Bài này hướng dẫn cài đặt, cấu hình, và các pattern prompt hiệu quả khi dùng GitLab MCP với cả Claude Code CLI và extension VS Code.

Cài Đặt và Kết Nối GitLab MCP Với Claude Code

Claude Code hỗ trợ đăng ký MCP server qua lệnh claude mcp add, hoặc khai báo trực tiếp trong file .mcp.json ở root project (khuyến khích cho team, vì file này commit được vào repo và mọi thành viên dùng chung cấu hình).

Cách nhanh nhất — đăng ký qua CLI:

claude mcp add gitlab \
  --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  --env GITLAB_API_URL=https://gitlab.com/api/v4 \
  -- npx -y @zereight/mcp-gitlab

Nếu muốn team dùng chung, tạo file .mcp.json ở root repo:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "https://gitlab.your-company.com/api/v4"
      }
    }
  }
}

Lưu ý dùng ${GITLAB_PERSONAL_ACCESS_TOKEN} để Claude Code inject giá trị từ biến môi trường của máy chạy, tránh commit token trực tiếp vào file này. Mỗi engineer tự set biến môi trường riêng (ví dụ trong .zshrc hoặc file .env không commit) theo token cá nhân của họ.

Sau khi thêm, xác nhận server đã kết nối bằng:

claude mcp list

Bạn sẽ thấy gitlab với status "connected". Nếu status là "failed", thường là do token sai scope, hoặc GITLAB_API_URL chưa đúng domain self-hosted.

Mẹo: Chạy claude mcp get gitlab để xem chi tiết config đã đăng ký — hữu ích khi debug case "hôm qua chạy được, hôm nay không kết nối được" (thường do token hết hạn hoặc VPN công ty bị disconnect).

Quản Lý Merge Request và Issue GitLab Từ Terminal

Sau khi kết nối, bạn có thể ra lệnh trực tiếp trong session Claude Code. Vài ví dụ prompt thực tế:

Liệt kê MR đang mở giao cho mình:

List all open merge requests in project company/backend/payment-service that are assigned to me, show title, MR IID, and pipeline status.

Tạo MR mới kèm mô tả tự sinh:

Create a merge request in project company/backend/payment-service from branch feature/add-refund-api into develop. Look at the diff between these branches, write a clear MR description in English summarizing what changed, and add labels "backend" and "needs-review".

Xem chi tiết một issue và trả lời trong comment:

Get issue #482 in project company/backend/payment-service, read the reported bug, then check if the root cause is already fixed in branch feature/fix-refund-race-condition by comparing the diff, and post a comment on the issue with your finding.

Merge một MR sau khi pipeline pass:

Check the pipeline status of merge request !156 in project company/backend/payment-service. If it's passed and has at least one approval, merge it using "squash and merge" strategy. If not, tell me what's blocking it.

Claude Code sẽ tự chọn tool phù hợp (get_merge_request, get_pipeline, merge_merge_request...) và show ra approval prompt trước khi thực hiện action có ghi (write action) — bạn có thể approve từng lệnh hoặc bật auto-approve cho tool cụ thể qua /permissions nếu tin tưởng.

Mẹo: Với action "merge", luôn giữ approval mode thủ công (không auto-approve) — đây là hành động không thể hoàn tác dễ dàng, một double-check của con người trước khi confirm là bắt buộc trong quy trình production.

GitLab MCP Bên Trong Extension Claude Code Cho VS Code

Extension Claude Code cho VS Code dùng chung MCP config từ .mcp.json của project — bạn không cần đăng ký lại. Mở Claude Code panel trong VS Code, extension sẽ tự đọc .mcp.json ở root workspace và kết nối GitLab MCP tương tự CLI.

Khác biệt UX đáng chú ý so với CLI:

  • Approval UI trực quan hơn: Mỗi lần agent gọi tool có side-effect (tạo MR, comment, merge), VS Code hiện diff/preview ngay trong panel trước khi bạn click "Allow" — dễ review hơn so với đọc raw JSON trong terminal.
  • Context từ file đang mở: Khi bạn đang mở file trong editor và hỏi agent về MR liên quan tới file đó, Claude Code tự động đưa thêm context (đường dẫn file, vùng code đang chọn) vào prompt — giúp câu lệnh ngắn hơn mà agent vẫn hiểu đúng ý.
  • Cấu hình permission ở settings.json: Bạn có thể set permission mode riêng cho tool GitLab MCP trong .claude/settings.json:
{
  "permissions": {
    "allow": [
      "mcp__gitlab__list_merge_requests",
      "mcp__gitlab__get_merge_request",
      "mcp__gitlab__get_pipeline"
    ],
    "ask": [
      "mcp__gitlab__create_merge_request",
      "mcp__gitlab__create_merge_request_note"
    ],
    "deny": [
      "mcp__gitlab__merge_merge_request"
    ]
  }
}

Với cấu hình này, các tool chỉ-đọc (list_merge_requests, get_pipeline) chạy tự động không hỏi, còn action tạo/comment thì luôn hỏi trước, và action merge bị deny tuyệt đối — agent sẽ báo lỗi permission nếu cố gọi.

Mẹo: Commit file .claude/settings.json này vào repo để cả team dùng chung policy an toàn — tránh trường hợp một bạn dev vô tình bật auto-allow cho merge_merge_request trên máy cá nhân.

Viết Prompt Hiệu Quả Cho GitLab MCP Với Claude Code

Chất lượng output phụ thuộc rất nhiều vào cách bạn viết prompt. Một số pattern hiệu quả đã được kiểm chứng qua thực tế sử dụng:

  • Luôn chỉ rõ project path đầy đủ: Thay vì "check the MR", nói rõ "check MR !156 in project company/backend/payment-service" — tránh agent phải đoán hoặc gọi search_repositories tốn thêm round-trip.
  • Yêu cầu tường trình trước khi hành động (dry-run): "Show me what you would write in the MR description before creating it" giúp bạn review nội dung trước khi agent thực sự gọi create_merge_request.
  • Kết hợp git local + GitLab MCP: Prompt kiểu "Run git diff develop...HEAD locally, then create a merge request on GitLab summarizing that diff" cho kết quả chính xác hơn là để agent tự suy luận diff hoàn toàn qua API.
  • Chia nhỏ task pipeline debug: Với pipeline fail phức tạp, thay vì "fix the pipeline", chia bước: "1) get the failed job logs, 2) identify root cause, 3) propose fix in code, 4) after I confirm, push fix and re-trigger pipeline" — agent theo sát bước sẽ ít bị lạc hướng hơn so với một prompt gộp tất cả.
  • Đặt convention rõ trong CLAUDE.md: Ghi sẵn quy tắc label, format MR description chuẩn của team (ví dụ template ## What / ## Why / ## How to test) vào file CLAUDE.md ở root — agent đọc file này mỗi session và tự áp dụng convention mà không cần bạn nhắc lại mỗi lần.

Mẹo: Lưu lại 5-10 prompt mẫu hay dùng nhất của team thành snippet trong README hoặc file .claude/commands/ — biến chúng thành slash command tái sử dụng, giảm thời gian gõ lại prompt dài mỗi lần.

Mẹo Thực Chiến

Vài kinh nghiệm tổng hợp khi vận hành GitLab MCP với Claude Code hàng ngày:

  • Nếu bạn làm việc với nhiều project GitLab khác domain (một self-hosted, một gitlab.com), đăng ký hai MCP server riêng với tên khác nhau (gitlab-internal, gitlab-cloud) thay vì cố gộp chung một server — tránh nhầm token/URL.
  • Bật log MCP bằng claude --mcp-debug khi setup lần đầu để thấy rõ request/response thật giữa Claude Code và GitLab MCP server — rất hữu ích khi debug lỗi 401/403.
  • Với repo lớn, giới hạn agent chỉ lấy diff theo file cụ thể thay vì toàn bộ MR khi review, để không làm đầy context window một cách không cần thiết.

Mẹo: Định kỳ chạy claude mcp list mỗi đầu tuần để rà soát MCP server nào không còn dùng nữa — dọn dẹp giảm rủi ro token cũ bị bỏ quên vẫn còn active.

Tiếp GitLab MCP với OpenCode