·

GitHub MCP với Gemini CLI

Cài đặt GitHub MCP trong Gemini CLI để AI agent có thể quản lý repository, pull request và issue ngay trong trình soạn thảo.

Gemini CLI là công cụ agentic coding chạy trong terminal do Google phát hành, mã nguồn mở, dùng model Gemini làm bộ não cho agent. Điểm khác biệt lớn nhất của Gemini CLI so với các coding agent khác nằm ở context window (cửa sổ ngữ cảnh) cực lớn của model Gemini — lên tới 1 triệu token ở một số bản — cho phép agent "nhồi" nguyên một PR lớn, cả lịch sử issue dài, hoặc nhiều file liên quan cùng lúc mà không phải cắt bớt. Kết hợp với GitHub MCP, Gemini CLI trở thành một trợ lý mạnh cho những tác vụ cần "đọc nhiều, hiểu tổng thể" — ví dụ tổng hợp một PR khổng lồ gồm hàng chục file thay đổi thành một bản mô tả mạch lạc. Bài này hướng dẫn cài đặt, cấu hình, một ví dụ thực chiến, và so sánh trực diện hành vi GitHub MCP giữa Gemini CLI và Claude Code để bạn chọn đúng công cụ cho đúng việc.

Cài Đặt và Kết Nối GitHub MCP với Gemini CLI

Cài Gemini CLI qua npm (yêu cầu Node.js >= 20) hoặc qua Homebrew trên macOS:

npm install -g @google/gemini-cli
brew install gemini-cli

gemini --version

Lần đầu chạy gemini, CLI sẽ hỏi bạn đăng nhập Google account (dùng free tier với hạn mức request theo ngày) hoặc nhập API key từ Google AI Studio / Vertex AI nếu bạn cần hạn mức cao hơn cho công việc production.

Gemini CLI đọc cấu hình MCP server từ settings.json, có ba cấp: ~/.gemini/settings.json (global, áp dụng mọi project), .gemini/settings.json (theo project, ưu tiên cao hơn global), và biến môi trường override tại thời điểm chạy. Khối cấu hình MCP nằm dưới key mcpServers.

Cách 1 — Kết nối qua stdio, chạy GitHub MCP server local bằng Docker:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "-e", "GITHUB_TOOLSETS=repos,issues,pull_requests",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

Cách 2 — Kết nối qua HTTP tới endpoint MCP do GitHub host (không cần Docker):

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer $GITHUB_TOKEN"
      },
      "trust": false
    }
  }
}

Field trust đáng chú ý riêng: khi để false (mặc định, và nên giữ như vậy), Gemini CLI sẽ hỏi xác nhận (confirmation prompt) mỗi khi agent định gọi một tool có khả năng thay đổi dữ liệu (create, update, merge, delete) từ server này. Đây là lớp phòng vệ built-in rất đáng dùng cho GitHub MCP — chỉ nên set trust: true cho server bạn tuyệt đối tin tưởng và đã kiểm chứng hành vi kỹ (ví dụ chạy trong pipeline CI đã được review).

Sau khi lưu settings.json, mở gemini trong repo và gõ lệnh /mcp để xem danh sách server đã kết nối cùng số lượng tool mỗi server expose; gõ /mcp desc để xem mô tả chi tiết từng tool nếu bạn cần kiểm tra agent "nhìn thấy" đúng công cụ mong đợi hay chưa.

Về token, tương tự các MCP client khác, hãy dùng fine-grained PAT scoped theo đúng repo cần dùng, tối thiểu quyền Contents, Issues, Pull requests ở mức Read and write (hoặc chỉ Read nếu bạn chỉ cần agent phân tích/báo cáo, không thao tác ghi).

Mẹo: Giữ trust: false cho server GitHub trong mọi cấu hình dùng ở máy cá nhân. Chi phí là bạn phải xác nhận thêm một bước mỗi lần agent muốn ghi dữ liệu lên GitHub, nhưng đổi lại bạn luôn là người bấm nút cuối cùng cho mọi thay đổi — với một server có quyền merge code hoặc xoá branch, bước xác nhận này không phải phiền toái, mà là lưới an toàn bắt buộc.

Quản Lý GitHub Repos và Pull Requests từ Gemini CLI

Với GitHub MCP đã kết nối, bạn điều khiển toàn bộ vòng đời PR và repo bằng ngôn ngữ tự nhiên ngay trong session gemini. Nhờ context window lớn, Gemini CLI đặc biệt mạnh ở việc xử lý những PR "khủng" mà agent khác phải cắt bớt diff:

Lấy toàn bộ diff của PR #915 (dù diff dài), đọc kỹ tất cả file thay đổi,
và tóm tắt theo nhóm: thay đổi logic nghiệp vụ, thay đổi test, thay đổi
config/infra. Chỉ ra file nào có rủi ro breaking change cao nhất.

So sánh 3 pull request đang mở nhắm vào cùng module payment: PR #901, #915,
#920. Chỉ ra xem có xung đột logic giữa chúng không, dù chưa merge, dựa
trên diff của từng PR.

Tạo một release branch từ main, cherry-pick các commit đã merge vào main
trong 7 ngày qua có gắn label "backport-candidate", và mở PR từ release
branch đó về branch release/v2.4.

Prompt thứ ba là ví dụ rõ cho việc kết hợp local git operation (cherry-pick — Gemini CLI có quyền chạy shell command trong sandbox) với GitHub MCP (tạo PR, đọc label) trong cùng một chuỗi hành động — một use case chỉ khả thi khi agent có cả quyền truy cập local repo và GitHub API.

Với thao tác quản lý repo cấp cao hơn (branch protection, quản lý webhook, cấu hình Actions secrets), GitHub MCP server có expose một số tool thuộc toolset repos và actions, nhưng hãy luôn giữ nguyên tắc: bật đúng toolset cần dùng, không bật all tràn lan, để giảm rủi ro agent "tiện tay" gọi nhầm tool nhạy cảm khi bạn chỉ định làm việc khác.

Mẹo: Khi giao Gemini CLI xử lý nhiều PR liên quan cùng lúc (như ví dụ so sánh 3 PR trên), luôn yêu cầu nó trình bày kết luận dưới dạng bảng so sánh có cột "mức độ tin cậy của nhận định" — model xử lý lượng context lớn vẫn có thể bỏ sót chi tiết ở phần giữa diff dài, nên buộc nó tự đánh giá độ tin cậy giúp bạn biết chỗ nào cần tự kiểm tra lại bằng mắt.

Ví Dụ Thực Chiến: Tự Động Sinh Mô Tả Pull Request Trong Gemini CLI

Viết PR description (mô tả pull request) đầy đủ, đúng convention là việc ai cũng biết nên làm nhưng thường bị lười bỏ qua khi deadline gấp. Đây là bài toán rất hợp với Gemini CLI nhờ khả năng nạp toàn bộ diff lớn vào context một lần. Quy trình từng bước:

Bước 1 — Đứng tại branch feature, đảm bảo đã push commit mới nhất, rồi mở Gemini CLI:

git push origin feature/refund-partial-amount
gemini

Bước 2 — Yêu cầu agent phân tích thay đổi cả ở local và trên GitHub:

So sánh branch hiện tại với main (dùng git diff cục bộ), đồng thời kiểm tra
xem đã có pull request nào mở từ branch này chưa (dùng GitHub MCP list_pull_requests
filter theo head branch). Nếu chưa có PR, chuẩn bị tạo mới.

Bước 3 — Yêu cầu sinh nội dung PR theo template chuẩn của team:

Dựa trên diff, soạn PR description theo template sau, viết bằng tiếng Anh
kỹ thuật (code/identifier giữ nguyên):

## Summary
(1-2 câu mô tả PR làm gì và tại sao)

## Changes
- (bullet từng thay đổi chính, nhóm theo file/module)

## Testing
- (mô tả cách đã test: unit test mới, test case manual)

## Risk & Rollback
- (rủi ro nếu có, cách rollback nếu cần)

Không suy diễn phần Testing nếu diff không có test mới — nếu vậy, ghi rõ
"Chưa có test tự động, cần bổ sung" thay vì bịa ra.

Câu lệnh cuối trong bước 3 rất quan trọng: nó chặn trước hiện tượng agent "ảo tưởng" (hallucination) tự bịa ra là đã test kỹ trong khi thực tế diff không có file test nào thay đổi — một lỗi khá hay gặp nếu bạn không rào prompt rõ ràng.

Bước 4 — Review nội dung agent soạn, chỉnh tay nếu cần:

Đọc bản description agent trả về. Nếu thấy phần "Risk & Rollback" mô tả chưa đủ (agent thường đánh giá thấp rủi ro nếu không có thêm ngữ cảnh nghiệp vụ), bổ sung trực tiếp:

Bổ sung vào Risk: tính năng refund một phần ảnh hưởng trực tiếp bảng
ledger tài chính, cần QA xác nhận trên staging trước khi merge vào main.

Bước 5 — Tạo PR thật (hoặc update PR draft đã có) với nội dung đã chốt:

Tạo pull request từ feature/refund-partial-amount vào main, title theo
Conventional Commits ("feat: support partial refund amount"), dùng đúng
nội dung description đã chốt ở trên. Gắn label "needs-qa".

Agent gọi create_pull_request (hoặc update_pull_request nếu PR đã tồn tại) với body chính xác là bản bạn đã duyệt ở bước 4 — không phải bản thô ban đầu. Toàn bộ quy trình mất khoảng 3-5 phút, so với 15-20 phút viết tay một PR description tử tế, mà chất lượng đầu ra thường đồng đều hơn vì agent không "lười" bỏ qua mục Testing hay Risk như con người đôi khi vẫn làm.

Mẹo: Lưu template PR description ở bước 3 thành một file .gemini/prompts/pr-description-template.md trong repo, rồi mỗi lần dùng chỉ cần bảo agent "dùng template PR description trong repo" — vừa nhất quán format giữa các PR, vừa tránh phải gõ lại prompt dài mỗi lần.

So Sánh Hành Vi GitHub MCP Giữa Gemini CLI và Claude Code

Nếu bạn đã dùng GitHub MCP với Claude Code CLI (bài trước trong module này), dưới đây là những khác biệt thực chiến đáng lưu ý khi chuyển qua lại giữa hai công cụ, hoặc khi quyết định dùng công cụ nào cho tác vụ nào:

  • Context window: Gemini CLI (model Gemini) có context window lớn hơn đáng kể so với các bản Claude Code thường dùng, nên xử lý PR diff khổng lồ hoặc lịch sử issue dài mà không cần cắt bớt là lợi thế rõ của Gemini CLI. Ngược lại, với tác vụ cần suy luận sâu, nhiều bước, độ chính xác tool-calling cao trên schema phức tạp (như GitHub MCP với toolset đầy đủ), Claude Code thường cho kết quả ổn định hơn.
  • Cơ chế permission/trust: Gemini CLI có field trust per-server, chặn xác nhận theo từng lệnh ghi khi trust=false. Claude Code dùng cơ chế allowlist trong settings (permissions.allow) khai báo trước pattern tool được phép chạy tự động, phần còn lại luôn hỏi. Cả hai đều an toàn nếu cấu hình đúng, nhưng cách vận hành khác nhau: Gemini CLI hỏi theo tình huống thực tế lúc chạy, Claude Code quyết theo rule khai báo sẵn — Claude Code phù hợp hơn khi bạn muốn workflow tự động chạy không cần người trực chờ xác nhận cho các action đã được whitelist kỹ.
  • Độ ổn định tool-calling trên schema lớn: Với GitHub MCP toolset đầy đủ (hàng chục tool), cả hai đều thỉnh thoảng chọn nhầm tool gần giống nhau (ví dụ update_issue vs add_issue_labels). Kinh nghiệm thực tế: giảm toolset xuống mức cần thiết giúp cải thiện độ chính xác ở cả hai công cụ, nhưng mức độ nhạy cảm với việc này khác nhau theo phiên bản model — luôn benchmark lại khi bạn đổi model version.
  • Chi phí và hạn mức: Gemini CLI có free tier khá rộng rãi cho cá nhân (giới hạn theo request/ngày qua Google account), phù hợp để bạn thử nghiệm quy trình GitHub MCP mà không lo chi phí ban đầu. Claude Code tính theo usage API/plan Claude, chi phí rõ ràng hơn cho việc chạy production liên tục nhưng không có free tier tương đương cho khối lượng lớn.
  • Tích hợp editor: Claude Code có extension VS Code chính thức tích hợp mượt vào IDE (đã nói ở bài trước), còn Gemini CLI thiên về mô hình terminal-first, ít gắn sâu vào IDE hơn — nếu bạn cần workflow "click trong IDE, xem diff trực quan trước khi agent thao tác", Claude Code + VS Code hiện mượt hơn.
  • Xử lý lỗi và retry khi GitHub API rate limit: Cả hai công cụ đều không có cơ chế retry tự động thông minh built-in cho lỗi 403 rate-limit từ GitHub MCP server — bạn cần tự nhắc agent "nếu gặp rate limit, dừng và báo cho tôi" để tránh vòng lặp gọi lại vô nghĩa tốn token.

Kết luận thực chiến: dùng Gemini CLI khi bài toán cần "đọc nhiều, hiểu tổng thể" trên dữ liệu GitHub cồng kềnh (PR lớn, nhiều issue, lịch sử dài); dùng Claude Code khi bài toán cần workflow nhiều bước chính xác, tool-calling phức tạp, và tích hợp sâu vào vòng lặp edit-review trong IDE. Không có công cụ nào thắng tuyệt đối — đội ngũ có kinh nghiệm thường dùng cả hai, chọn theo tính chất công việc.

Mẹo: Nếu team bạn dùng cả Gemini CLI và Claude Code, hãy đảm bảo cả hai cùng đọc một file cấu hình toolset GitHub MCP dùng chung (ví dụ cùng list biến môi trường GITHUB_TOOLSETS trong .env của repo) — tránh tình trạng agent này thấy tool khác agent kia do cấu hình lệch nhau, dẫn tới hành vi không nhất quán giữa các thành viên team.

Mẹo

Một số kinh nghiệm rời rạc khác nên biết khi vận hành GitHub MCP qua Gemini CLI lâu dài:

  • Theo dõi hạn mức free tier: Nếu dùng tài khoản Google cá nhân, để ý cảnh báo hạn mức request/ngày — khi chạy workflow agentic có vòng lặp gọi nhiều tool GitHub MCP liên tiếp, bạn tiêu hạn mức nhanh hơn tưởng.
  • Kiểm tra /mcp desc sau mỗi lần update image: Khi GitHub cập nhật github-mcp-server, tên tool hoặc tham số có thể thay đổi nhẹ giữa các version — chạy lại /mcp desc để chắc chắn agent vẫn "nhìn thấy" đúng tool bạn quen dùng.
  • Ghi log quyết định quan trọng: Với các thao tác ghi ảnh hưởng lớn (merge, xoá branch, đổi branch protection), yêu cầu agent luôn in ra tóm tắt hành động đã thực hiện vào cuối phiên — hữu ích khi cần audit lại sau này ai/agent nào đã làm gì.
  • Đừng tin tuyệt đối phần tóm tắt diff dài: Dù context window lớn, model vẫn có thể lược bớt chi tiết khi tóm tắt diff hàng nghìn dòng — với thay đổi ảnh hưởng bảo mật hoặc dữ liệu tài chính, luôn tự đọc lại đoạn diff gốc quan trọng, đừng chỉ tin bản tóm tắt của agent.

Mẹo: Đặt lịch review định kỳ (hàng tháng) cấu hình settings.json và scope PAT đang dùng cho GitHub MCP — token và toolset thường bị "phình" dần theo thời gian khi có người thêm quyền cho một use case tạm thời rồi quên thu hồi lại, tạo ra rủi ro bảo mật âm ỉ mà không ai để ý.

Tiếp GitHub MCP với Cursor