Kết nối GitHub MCP với Claude Code: hướng dẫn từng bước (2026)

GitHub MCP với Claude Code là gì (và làm được gì)?

GitHub MCP server là cầu nối để Claude Code đọc và thao tác trực tiếp với GitHub bằng ngôn ngữ tự nhiên - không cần bạn rời terminal hay copy-paste thủ công. MCP (Model Context Protocol) là chuẩn mở giúp AI kết nối với công cụ ngoài; nếu bạn chưa nắm nền, đọc trước bài MCP là gì và hoạt động thế nào.

Sau khi kết nối, bạn có thể yêu cầu Claude những việc như: liệt kê repo và issue đang mở, tạo issue mới, mở pull request, review code trong một PR, tìm đoạn code theo mô tả, hay đọc nội dung file trong repo. Thay vì mở trình duyệt và click qua GitHub, bạn chỉ gõ một câu tiếng Việt hoặc tiếng Anh và Claude gọi GitHub API giúp bạn. Đây chính là điểm khác biệt so với việc dùng lệnh gh rời rạc: Claude hiểu ngữ cảnh cả phiên làm việc và tự chọn tool phù hợp.

Một ví dụ thực tế: khi đang sửa một bug, bạn có thể nói "tìm issue nào liên quan tới lỗi timeout này rồi tóm tắt các bình luận", Claude sẽ tra GitHub, đọc issue và trả lời ngay trong terminal - không cần bạn chuyển cửa sổ. Sau khi vá xong, bạn nói tiếp "mở PR từ branch hiện tại và tham chiếu tới issue đó". Toàn bộ chuỗi thao tác diễn ra trong một cuộc trò chuyện, giữ nguyên ngữ cảnh code bạn đang làm. Đó là lý do nhiều dev gắn GitHub MCP như một công cụ mặc định thay vì bật/tắt từng lần.

Chuẩn bị trước khi bắt đầu (checklist)

Trước khi thêm server, kiểm tra nhanh những thứ sau:

• Claude Code đã cài và chạy được trong terminal - nếu chưa, xem cách cài đặt Claude Code.
• Tài khoản GitHub có quyền trên repo bạn muốn Claude thao tác.
• Chọn một cách kết nối: Remote HTTP (khuyên dùng - nhanh, không cần cài gì thêm) hoặc Docker (nếu bạn muốn chạy server ngay trên máy). Với hầu hết mọi người, Remote HTTP là đủ.
• Nếu chọn Docker: cài sẵn Docker Desktop và mở nó lên trước khi thêm server.

Cả bài này chỉ mất khoảng 5-10 phút nếu bạn đi theo Remote HTTP.

Bước 1 - Tạo GitHub Personal Access Token (PAT)

GitHub MCP cần một token để thay bạn gọi API. GitHub có hai loại token: classic (quyền theo scope rộng) và fine-grained (quyền theo từng repo). Nên dùng fine-grained token vì bạn giới hạn được đúng repo và đúng quyền, giảm thiệt hại nếu chẳng may token bị lộ:

1. Vào GitHub → ảnh đại diện → Settings.
2. Kéo xuống cuối menu trái, chọn Developer settings.
3. Chọn Personal access tokens → Fine-grained tokens → Generate new token.
4. Đặt tên (ví dụ claude-code-mcp), chọn thời hạn hết hạn hợp lý (30-90 ngày).
5. Ở Repository access, chọn Only select repositories và chỉ tick những repo bạn cho phép Claude đụng vào.
6. Ở Permissions → Repository permissions, cấp quyền tối thiểu bạn cần: Contents (đọc/ghi file), Issues, Pull requests. Nếu làm việc với tổ chức, thêm read:org.
7. Bấm Generate token và copy token ngay.

Cảnh báo bảo mật: GitHub chỉ hiển thị token một lần duy nhất. Copy và dán tạm vào nơi an toàn (password manager). KHÔNG commit token vào repo, KHÔNG dán vào file được git theo dõi. Chỉ cấp quyền ghi khi bạn thực sự muốn Claude tự tạo/sửa nội dung.

Bước 2 - Thêm GitHub MCP server (cách khuyên dùng: Remote HTTP)

Đây là cách nhanh nhất và không cần Docker. Mở terminal, thay YOUR_PAT bằng token vừa tạo và chạy:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_PAT"

Nếu bạn thích cấu hình dạng JSON (tiện khi copy sẵn), dùng bản thay thế:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_PAT"}}'

Chọn phạm vi cấu hình bằng cờ -s:

• -s local (mặc định): chỉ áp dụng cho máy này, trong thư mục hiện tại.
• -s user: dùng chung cho mọi project của bạn - hữu ích khi bạn muốn GitHub MCP luôn sẵn sàng và token không nằm trong repo.
• -s project: lưu vào .mcp.json và chia sẻ với cả team qua git. Tiện cho team nhưng cẩn thận: đừng để token thật lọt vào file này.

Ví dụ dùng chung cho mọi project: thêm -s user vào cuối lệnh claude mcp add ở trên. Chi tiết cú pháp claude mcp add có trong tài liệu MCP chính thức của Claude Code (cập nhật 2026).

Lưu ý về OAuth: tại thời điểm 08/2026, luồng OAuth chưa hỗ trợ đầy đủ cho GitHub MCP remote trên Claude Code, nên dùng PAT như trên là cách ổn định nhất.

Bước 3 (thay thế) - Chạy GitHub MCP bằng Docker (local)

Nếu bạn muốn server chạy hẳn trên máy (ví dụ để kiểm soát hoàn toàn hoặc chạy trong môi trường cách ly), dùng image chính chủ ghcr.io/github/github-mcp-server. Đảm bảo Docker Desktop đang mở, rồi chạy:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Khi nào chọn Docker, khi nào chọn Remote HTTP? Bảng ngắn dưới đây:

⚠️ Đừng dùng npm package đã khai tử

Đây là lỗi phổ biến nhất. Rất nhiều hướng dẫn cũ (kể cả tiếng Việt) còn dạy cài @modelcontextprotocol/server-github qua npm. Package community này đã bị khai tử (deprecated) từ 04/2025 - làm theo sẽ dẫn tới server không kết nối hoặc lỗi khó hiểu. Cách đúng năm 2026 là dùng remote HTTP hoặc Docker image chính chủ từ repo github/github-mcp-server (nguồn chính thức của GitHub, cập nhật 2026).

Bước 4 - Kiểm tra & dùng thử

Sau khi thêm, xác nhận server đã "Connected":

claude mcp list

Bạn sẽ thấy github với trạng thái kết nối. Tiếp theo, mở Claude Code và gõ:

/mcp

Lệnh /mcp liệt kê tất cả tool GitHub đang khả dụng. Giờ thử vài prompt thật:

• "Liệt kê các repo GitHub của tôi."
• "Tạo một issue trong repo owner/repo với tựa đề: Cải thiện docs cài đặt."
• "Tóm tắt các pull request đang mở trong repo này."

Nếu Claude trả về đúng dữ liệu và tạo được issue, bạn đã kết nối thành công.

Sửa lỗi thường gặp (troubleshooting)

Phần lớn lỗi khi kết nối GitHub MCP đến từ ba nguyên nhân: token sai/thiếu quyền, dùng nhầm cách cài cũ, hoặc chưa khởi động lại Claude Code sau khi thêm server. Nếu có trục trặc, đối chiếu triệu chứng của bạn với bảng sau:

Mẹo chung: khi nghi ngờ, chạy claude mcp remove github rồi thêm lại từ đầu - cách này xử lý được phần lớn lỗi cấu hình.

Bảo mật & giới hạn quyền (read-only, toolsets)

Cho một agent quyền ghi vào GitHub là tiện, nhưng có rủi ro thật: một prompt mơ hồ có thể khiến Claude tạo issue/PR ngoài ý muốn, hoặc một token quá rộng quyền bị lộ sẽ ảnh hưởng nhiều repo. Vài nguyên tắc để an toàn:

• Cấp token tối thiểu: chỉ chọn đúng repo cần thiết và đúng quyền cần dùng.
• Không commit token: ưu tiên -s user để token không nằm trong repo; nếu buộc dùng -s project, đưa token qua biến môi trường thay vì ghi thẳng.
• Dùng read-only khi chỉ cần đọc: GitHub MCP server hỗ trợ chế độ read-only và bật/tắt từng nhóm toolsets - giới hạn để Claude chỉ đọc, không ghi, khi bạn chỉ muốn review hay tra cứu.
• Đặt thời hạn token ngắn và thu hồi khi không dùng nữa.

Trung thực mà nói: không có cấu hình nào an toàn tuyệt đối khi bạn trao quyền ghi cho AI - hãy giữ token gọn quyền và kiểm tra lại hành động quan trọng.

Bước tiếp: tự động hoá git workflow với Claude Code

Khi GitHub MCP đã chạy, bước tự nhiên tiếp theo là để Claude lo cả vòng đời thay đổi: tạo branch, commit theo chuẩn, mở PR và review. Đó là chủ đề của bài tự động hoá git workflow với Claude Code (sẽ cập nhật link khi bài lên).

Câu hỏi thường gặp (FAQ)

GitHub MCP có miễn phí không?

Bản thân GitHub MCP server (remote HTTP và Docker image chính chủ) miễn phí. Bạn chỉ cần một tài khoản GitHub và một Personal Access Token. Các thao tác vẫn tính vào hạn mức GitHub API bình thường của tài khoản bạn.

Có bắt buộc cài Docker không?

Không. Cách khuyên dùng là remote HTTP - chỉ một lệnh claude mcp add --transport http, không cần Docker. Docker chỉ cần khi bạn muốn chạy server cục bộ trên máy.

PAT cần scope gì?

Với fine-grained token, tối thiểu cấp quyền Contents, Issues và Pull requests trên đúng repo bạn muốn dùng. Thêm read:org nếu làm việc trong tổ chức. Đừng cấp quyền rộng hơn mức cần.

Gỡ GitHub MCP server thế nào?

Chạy claude mcp remove github. Nếu server được thêm ở phạm vi khác, chỉ định lại phạm vi tương ứng (ví dụ -s user) khi gỡ.

Khác gì so với dùng gh CLI?

gh là công cụ dòng lệnh bạn tự gõ từng lệnh. GitHub MCP để Claude tự gọi GitHub API theo ngữ cảnh cuộc trò chuyện - bạn ra yêu cầu bằng ngôn ngữ tự nhiên, Claude chọn tool và thực thi, kết hợp được với các bước khác trong cùng phiên làm việc.

OAuth dùng được chưa?

Tại 08/2026, OAuth chưa hỗ trợ đầy đủ cho GitHub MCP remote trên Claude Code, nên PAT vẫn là cách kết nối ổn định và được khuyên dùng.

Kết luận

Chỉ với 4 bước - tạo PAT → thêm server qua remote HTTP → kiểm tra bằng claude mcp list và /mcp → dùng thử - bạn đã cho Claude Code đọc và thao tác GitHub bằng ngôn ngữ tự nhiên. Điểm mấu chốt: dùng remote HTTP hoặc Docker chính chủ, tránh npm package đã khai tử, và giữ token gọn quyền, không commit vào repo. Muốn hiểu sâu hơn nền tảng, đọc MCP là gì và hoạt động thế nào; muốn đi tiếp phần tự động hoá, xem git workflow với Claude Code (link khi bài lên). Cần lệnh /mcp và các slash command khác? Xem slash commands trong Claude Code.