Hướng dẫn kết nối MCP Github Local Dev với Claude AI: Chi tiết từng bước cho người mới bắt đầu

Trong thời đại mà AI đang dần thay đổi cách chúng ta làm việc, việc tích hợp và kết nối nền tảng AI với các công cụ hỗ trợ là rất cần thiết. Ở đây chúng ta sẽ có Claude AI với Github thông qua MCP (Model Context Protocol) mở ra một kỷ nguyên mới cho developer. Thay vì phải chuyển đổi liên tục giữa editor, terminal và trình duyệt Github, giờ đây bạn có thể yêu cầu Claude tạo issue, push code, tìm kiếm repository và quản lý toàn bộ workflow Github - tất cả chỉ bằng ngôn ngữ tự nhiên ngay trong giao diện chat.

Bài viết này sẽ hướng dẫn bạn từng bước chi tiết cách thiết lập kết nối MCP Github với Claude Desktop, từ việc tạo Personal Access Token đến cấu hình file config và kiểm tra kết nối thành công. Dù bạn là developer mới hay đã có kinh nghiệm, hướng dẫn này đều được viết sao cho dễ hiểu và dễ thực hiện nhất.

Yêu cầu chuẩn bị trước khi bắt đầu

Để thiết lập kết nối MCP Github thành công, bạn cần chuẩn bị:

1. Claude Desktop App:MCP hiện chỉ hoạt động trên phiên bản Claude Desktop (Windows hoặc macOS), chưa hỗ trợ trên Web hay Mobile. Tải về tại: https://claude.ai/download

2. Tài khoản Github:Bạn cần có tài khoản Github đang hoạt động. Nếu chưa có, đăng ký miễn phí tại github.com

3. Node.js và NPM:MCP Github server chạy trên Node.js. Cài đặt phiên bản Node.js 16 trở lên từ Node.js — Run JavaScript Everywhere Chọn Get Node.js, sau đó chờ file cài đặt tải về và cài đặt, cài đặt Node.js rất đơn giản.

4. Quyền truy cập file hệ thống:Bạn cần biết cách mở và chỉnh sửa file JSON trên máy tính của mình (sử dụng Notepad, VS Code hoặc bất kỳ text editor nào).

Bước 1: Tạo Github Personal Access Token để liên kết với Claude

Trong lập trình, Local Dev (phát triển cục bộ) nghĩa là việc chạy mã nguồn, phần mềm hoặc các công cụ ngay trên máy tính cá nhân của bạn (PC/Laptop), chứ không phải chạy trên một máy chủ đám mây (Cloud) hay website tầm xa.

Github Personal Access Token (PAT) là một mã xác thực cho phép ứng dụng bên thứ ba (trong trường hợp này là Claude thông qua MCP) truy cập vào tài khoản Github của bạn mà không cần mật khẩu. Đây là bước quan trọng nhất trong quá trình thiết lập.

Các bước tạo Personal Access Token chi tiết

GitHub

Bước 1.1: Đăng nhập vào Github theo link trên và truy cập Settings. Nhấn vào avatar của bạn ở góc trên bên phải, chọn "Settings" từ menu dropdown.

Bước 1.2: Trong thanh sidebar bên trái, cuộn xuống cuối cùng và chọn "Developer settings".

Bước 1.3: Trong menu Developer settings, chọn "Personal access tokens" > "Tokens (classic)".

Bước 1.4: Nhấn nút "Generate new token" > "Generate new token (classic)".

Bước 1.5: Xác nhận mật khẩu Github hoặc mã xác nhận trong tài khoản email bạn đã liên kết với GitHub trước đó nếu được yêu cầu.

Bước 1.6: Điền thông tin token:

• Note: Đặt tên mô tả như "Claude MCP Github" hoặc "MCP Server Access" để dễ nhận biết sau này

• Expiration: Chọn thời hạn (khuyến nghị "90 days" hoặc "No expiration" nếu bạn muốn sử dụng lâu dài)

Bước 1.7: Chọn các quyền (scopes) cần thiết. Đây là phần quan trọng - bạn cần tick chọn các quyền sau:

• repo (Full control of private repositories) - Bắt buộc

• workflow (Update GitHub Action workflows) - Tích nếu bạn làm việc với Github Actions

• admin:org (nếu bạn muốn quản lý organization)

Bước 1.8: Cuộn xuống cuối trang và nhấn nút "Generate token" màu xanh.

Bước 1.9: QUAN TRỌNG - Sao chép token ngay lập tức! Token sẽ có dạng "ghp_xxxxxxxxxxxxxxxxxxxx". Nhấn vào icon copy hoặc chọn toàn bộ text và copy (Ctrl+C / Cmd+C). Lưu token này vào một nơi an toàn (ví dụ: password manager) vì Github sẽ CHỈ HIỂN THỊ MỘT LẦN DUY NHẤT. Nếu bạn mất token, bạn sẽ phải tạo token mới.

Bước 2: Cấu hình file Claude Desktop Config

Sau khi có Personal Access Token, bước tiếp theo là cấu hình file config của Claude Desktop để kết nối với MCP Github server.

Bước 2.1: Mở Claude Desktop App, nhấn vào avatar/email ở góc trên bên trái và chọn "Settings" (Cài đặt)

Bước 2.2: Trong sidebar trái, chọn "Developer"

Bước 2.3: Nhấn nút "Edit Config" - File sẽ tự động mở trong Notepad hoặc text editor mặc định, bạn có thể mở nó lên bằng Notepad để chỉnh sửa.

Tìm và mở file cấu hình

File cấu hình có tên là claude_desktop_config.json và nằm ở vị trí khác nhau tùy theo hệ điều hành:

Trên Windows:

%APPDATA%\Claude\claude_desktop_config.json

Đường dẫn đầy đủ thường là:

C:\Users\[TenNguoiDung]\AppData\Roaming\Claude\claude_desktop_config.json

Trên macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Cách nhanh nhất để tìm file trên Windows:

Cấu trúc file config chuẩn

Khi bạn mở file lần đầu, nó có thể trống hoặc chỉ có dấu ngoặc nhọn {}. Bạn cần thêm cấu hình MCP server theo đúng cấu trúc JSON sau:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Giải thích từng phần quan trọng:

• mcpServers: Object chứa tất cả các MCP server bạn muốn kết nối. Bạn có thể thêm nhiều server khác nhau vào đây.

• "github": Tên định danh cho server này. Bạn có thể đặt tên khác nhưng nên giữ nguyên "github" để dễ nhận biết.

• "command": "npx": Lệnh để chạy server. NPX là công cụ của Node.js cho phép chạy package mà không cần cài đặt global.

• "args": Các tham số cho lệnh npx:

- "-y": Tự động xác nhận cài đặt package

- "@modelcontextprotocol/server-github": Tên package chính thức của MCP Github server

• "env":Environment variables (biến môi trường) cho server:

- "GITHUB_PERSONAL_ACCESS_TOKEN": Thay "ghp_YOUR_TOKEN_HERE" bằng token bạn đã tạo trên Github ở Bước 1.

Lưu ý quan trọng khi chỉnh sửa file JSON:

• Đảm bảo sử dụng dấu ngoặc kép (") chứ không phải dấu ngoặc đơn (').

• Mỗi dòng (trừ dòng cuối trong một object) phải có dấu phẩy ở cuối.

• Kiểm tra số lượng ngoặc nhọn mở { và đóng } phải bằng nhau.

• Có thể sử dụng JSONLint.com để kiểm tra cú pháp JSON có hợp lệ không.

Lưu file và khởi động lại Claude

1. Sau khi chỉnh sửa xong, nhấn Ctrl+S (Windows) hoặc Cmd+S (macOS) để lưu file.

2. Thoát hoàn toàn khỏi Claude Desktop App (không chỉ đóng cửa sổ mà phải quit/exit ứng dụng). Tốt nhất là bạn nên tắt trong Task Manager.

3. Mở lại Claude Desktop, ứng dụng sẽ đọc file config mới và tự động khởi chạy MCP Github server.

Bước 3: Kích hoạt và kiểm tra kết nối

Kích hoạt MCP Github trong chat

Sau khi khởi động lại Claude Desktop, MCP Github server đã sẵn sàng nhưng chưa được kích hoạt trong chat. Để sử dụng, bạn cần bật nó cho từng cuộc hội thoại:

Cách 1 - Sử dụng nút "+":

1. Trong giao diện chat, nhấn vào nút "+" ở góc dưới bên trái

2. Trong menu hiển thị, tìm mục "Connectors"

3. Bật công tắc (toggle) bên cạnh "github" để kích hoạt

4. Bạn sẽ thấy biểu tượng "G" màu đen hoặc tên "github" xuất hiện ở thanh công cụ, chứng tỏ connector đã được kích hoạt

Cách 2 - Sử dụng phím tắt "/":

1. Gõ dấu "/" trong ô chat

2. Chọn "Connectors" từ menu

3. Bật "github"

Kiểm tra kết nối và phân quyền công cụ

Khi bạn kích hoạt MCP Github lần đầu tiên, Claude sẽ hiển thị danh sách các công cụ (tools) mà connector này cung cấp, kèm theo các tùy chọn phân quyền:

Trạng thái phân quyền:

• Needs approval (Cần phê duyệt): Mặc định, tất cả các công cụ sẽ ở chế độ này. Mỗi khi Claude muốn sử dụng một công cụ, bạn phải xác nhận thủ công.

• Allow once (icon bàn tay): Cho phép sử dụng công cụ một lần cho hành động hiện tại.

• Always allow (icon ngón tay cái): Luôn cho phép Claude sử dụng công cụ này mà không cần hỏi lại.

• Block (icon cấm): Cấm hoàn toàn việc sử dụng công cụ này.

Khuyến nghị phân quyền an toàn:

Các công cụ chỉ đọc (safe): Có thể để "Always allow" để tiện lợi

• search_repositories

• get_file_contents

Các công cụ ghi/thay đổi (cần thận trọng): Nên giữ "Needs approval" hoặc "Allow once"

• create_or_update_file

• push_files

• create_issue

• create_pull_request

• create_repository

Kiểm tra hoạt động bằng câu lệnh đơn giản

Để đảm bảo mọi thứ hoạt động, hãy thử một số câu lệnh sau:

Test 1 - Tìm kiếm repository:

"Tìm các repository công khai của tôi trên Github"

Test 2 - Đọc nội dung file:

"Đọc nội dung file README.md trong repository [tên-repo] của tôi"

Test 3 - Tạo issue (nếu đã cấp quyền):

"Tạo một issue test trong repository [tên-repo] với tiêu đề 'Test MCP Connection' và nội dung 'Đây là issue test để kiểm tra kết nối MCP Github'"

Nếu Claude có thể thực hiện các tác vụ này và trả về kết quả từ Github của bạn, chúc mừng - bạn đã thiết lập thành công!

Ví dụ thực tế sử dụng MCP Github

Sau khi thiết lập thành công, đây là một số workflow thực tế bạn có thể thực hiện:

Workflow 1: Tìm bug và tạo issue tự động

Bạn: "Đọc file src/auth/login.js trong repo my-web-app và tìm các vấn đề bảo mật tiềm ẩn"

Claude: [Sử dụng get_file_contents để đọc file] → Phân tích code → Phát hiện password được hardcode

Bạn: "Tạo một issue về vấn đề này với priority cao"

Claude: [Sử dụng create_issue] → Tạo issue với tiêu đề, mô tả chi tiết, label "security", "high-priority"

Workflow 2: Refactor code và push lên branch mới

Bạn: "Đọc file utils/helper.js, refactor để sử dụng async/await thay vì callback, rồi push lên branch feature/async-refactor"

Claude: [Đọc file] → Refactor code → [Tạo branch mới] → [Push file đã refactor] → Xác nhận thành công

Workflow 3: Tìm kiếm và so sánh code giữa các repo

Bạn: "So sánh cách implement authentication giữa repo project-a và project-b của tôi"

Claude: [Tìm kiếm repositories] → [Đọc file auth từ cả 2 repo] → So sánh và chỉ ra điểm khác biệt, ưu nhược điểm của mỗi approach

Quản lý và tối ưu hóa MCP Github

Xem trạng thái server trong Settings

Bạn có thể kiểm tra trạng thái của MCP Github server bất cứ lúc nào:

1. Mở Settings trong Claude Desktop

2. Chọn "Developer" trong sidebar

3. Mục "Local MCP servers" sẽ hiển thị:

• Tên server: "github"

• Trạng thái: "running" (màu xanh) nếu hoạt động bình thường

• Command: npx

• Arguments: -y @modelcontextprotocol/server-github

4. Nhấn "View Logs" để xem log chi tiết nếu có lỗi

Tool access modes - Tối ưu hiệu suất

Nếu bạn có nhiều connector (hơn 5-10 cái), việc tải tất cả công cụ cùng lúc có thể làm chậm Claude. Điều chỉnh chế độ tải:

1. Trong menu "+" hoặc "/", chọn "Connectors"

2. Nhấn "Tool access" ở cuối menu

3. Chọn chế độ phù hợp:

• Auto (Khuyến nghị):Hệ thống tự động quyết định

• Load tools when needed:Chỉ tải khi bạn thực sự sử dụng, tiết kiệm tài nguyên

Bảo mật token và best practices

Không commit file config vào Git: File claude_desktop_config.json chứa token nhạy cảm. Nếu bạn làm việc với dotfiles hoặc backup cấu hình, hãy thêm file này vào .gitignore

Sử dụng token có phạm vi hẹp: Chỉ cấp quyền "repo" nếu bạn chỉ làm việc với repository. Không cấp quyền admin:org trừ khi thực sự cần thiết.

Đặt thời hạn cho token: Thay vì "No expiration", hãy đặt thời hạn 90 ngày và tái tạo định kỳ để tăng cường bảo mật.

Thu hồi token cũ: Khi tạo token mới hoặc không còn sử dụng MCP Github, vào Github Settings > Developer settings > Personal access tokens và revoke (thu hồi) các token không dùng.

Backup cấu hình an toàn: Nếu cần backup file config, hãy mã hóa file hoặc lưu vào password manager thay vì lưu dạng plain text.

MCP Github là gì và tại sao bạn nên sử dụng?

MCP (Model Context Protocol) là một giao thức chuẩn được Anthropic phát triển để cho phép các AI model như Claude kết nối và tương tác với các công cụ, dịch vụ bên ngoài một cách an toàn và có cấu trúc. Nói đơn giản, MCP đóng vai trò như một cây cầu nối giữa Claude và các ứng dụng khác.

MCP Github connector là một server MCP chuyên biệt cho phép Claude truy cập và thao tác với Github repositories của bạn. Khi được kích hoạt, connector này cấp cho Claude các công cụ (tools) để thực hiện hàng loạt tác vụ phức tạp trên Github mà không cần bạn phải làm thủ công.

Các chức năng chính của MCP Github

Khi kết nối thành công, Claude có thể thực hiện hơn 26 công cụ (tools) khác nhau trên Github của bạn, bao gồm:

1. Quản lý repository:

• Tìm kiếm repositories (search_repositories)

• Tạo repository mới (create_repository)

• Fork repository (fork_repository)

2. Quản lý code và file:

• Đọc nội dung file (get_file_contents)

• Tạo hoặc cập nhật file (create_or_update_file)

• Push nhiều file cùng lúc (push_files)

3. Quản lý issue và pull request:

• Tạo issue mới (create_issue)

• Tạo pull request (create_pull_request)

• Tạo branch mới (create_branch)

Lợi ích thực tế: Thay vì phải mở terminal, gõ lệnh git, chuyển sang browser để tạo issue hay PR, bạn chỉ cần nói với Claude: "Tạo một issue về bug đăng nhập trong repo my-app" hoặc "Push file index.js này lên branch feature/login". Claude sẽ tự động thực hiện tất cả các bước cần thiết.

Kết luận: Nâng tầm năng suất với MCP Github

Việc kết nối MCP Github với Claude AI không chỉ đơn thuần là tích hợp thêm một công cụ - đó là sự thay đổi căn bản trong cách developer tương tác với code và quản lý dự án. Thay vì phải chuyển đổi liên tục giữa terminal, IDE, browser và Github, giờ đây bạn có một trợ lý AI thông minh có thể hiểu yêu cầu bằng ngôn ngữ tự nhiên và tự động thực hiện các tác vụ phức tạp.

Từ việc tìm kiếm repository, đọc và phân tích code, tạo issue, push changes, đến quản lý pull request - tất cả đều có thể được thực hiện chỉ bằng cách trò chuyện với Claude. Điều này không chỉ tiết kiệm thời gian mà còn giảm thiểu lỗi do context switching và cho phép bạn tập trung vào những công việc sáng tạo hơn.

Quan trọng nhất: Hãy nhớ rằng MCP Github chỉ là một trong nhiều connector có thể tích hợp với Claude. Khi bạn đã thành thạo việc thiết lập và sử dụng connector này, bạn có thể mở rộng hệ sinh thái của mình với các MCP server khác - từ quản lý database, tương tác với API, đến tự động hóa DevOps workflow.

Bắt đầu ngay hôm nay và trải nghiệm sức mạnh của AI-powered development workflow.

Xử lý sự cố thường gặp

Lỗi 1: Server không xuất hiện trong Connectors

Triệu chứng: Sau khi cấu hình file config và khởi động lại Claude, bạn không thấy "github" trong danh sách Connectors.

Nguyên nhân và cách khắc phục:

• Lỗi cú pháp JSON:Kiểm tra lại file config bằng công cụ như JSONLint.com. Các lỗi phổ biến:

- Thiếu hoặc thừa dấu phẩy

- Sử dụng dấu ngoặc đơn ' thay vì dấu ngoặc kép "

- Không đóng ngoặc nhọn {} hoặc ngoặc vuông []

• Đường dẫn file sai:Đảm bảo bạn đang chỉnh sửa đúng file claude_desktop_config.json ở vị trí chính xác (sử dụng nút "Edit Config" trong Settings để chắc chắn).

• Chưa khởi động lại hoàn toàn:Đảm bảo bạn đã thoát hoàn toàn (quit) Claude Desktop, không chỉ đóng cửa sổ.

Lỗi 2: Server xuất hiện nhưng status không phải "running"

Triệu chứng: "github" xuất hiện trong Settings > Developer > Local MCP servers nhưng không có status "running" hoặc hiển thị lỗi.

Nguyên nhân và cách khắc phục:

• Chưa cài Node.js hoặc NPX:

1. Mở Terminal (macOS/Linux) hoặc Command Prompt (Windows)

2. Gõ: node --version

3. Gõ: npx --version

4. Nếu báo lỗi "command not found", cài Node.js từ nodejs.org

• Package không tải được:Thử chạy thủ công trong terminal:

npx -y @modelcontextprotocol/server-github

Nếu gặp lỗi network, kiểm tra kết nối internet hoặc proxy/firewall.

• Xem log chi tiết:Nhấn "View Logs" trong Settings > Developer để xem thông báo lỗi cụ thể.

Lỗi 3: Connector hoạt động nhưng Claude báo lỗi khi thực hiện tác vụ

Triệu chứng: Claude hiển thị lỗi "Authentication failed" hoặc "Permission denied" khi bạn yêu cầu tạo issue, push file, v.v.

Nguyên nhân và cách khắc phục:

• Token không hợp lệ:

- Kiểm tra token bắt đầu bằng "ghp_" và không có khoảng trắng thừa

- Vào Github Settings > Developer settings > Personal access tokens, kiểm tra token có còn active không

- Nếu token hết hạn, tạo token mới và cập nhật vào file config

• Thiếu quyền (scopes):

- Đảm bảo token có quyền "repo" (full control)

- Nếu làm việc với organization, cần thêm quyền "admin:org"

- Tạo lại token với đầy đủ quyền cần thiết

• Repository không tồn tại hoặc không có quyền truy cập:

- Kiểm tra tên repository có chính xác không (phân biệt chữ hoa/thường)

- Đảm bảo bạn có quyền write/admin với repository đó

Lỗi 4: Claude không hiểu câu lệnh liên quan đến Github

Triệu chứng: Claude trả lời chung chung thay vì sử dụng MCP Github tools.

Nguyên nhân và cách khắc phục:

• Connector chưa được kích hoạt cho chat này:Kiểm tra xem biểu tượng "G" hoặc "github" có hiển thị ở thanh công cụ không. Nếu không, bật connector qua menu "+" > Connectors.

• Câu lệnh không rõ ràng:Hãy cụ thể hơn. Thay vì "tìm code", nói "tìm file index.js trong repository my-app". Càng chi tiết, Claude càng dễ hiểu và sử dụng đúng tool.