Hướng dẫn cách tích hợp Google Docs MCP với Claude Code từ A-Z

Tích hợp Google Docs MCP với Claude Code giúp kết nối tài liệu Google Docs với quy trình lập trình bằng AI, từ đọc, tóm tắt đến tạo và cập nhật nội dung trực tiếp. Bài viết hướng dẫn chi tiết cách thiết lập MCP, cấu hình OAuth, kết nối Claude Code, sử dụng các tính năng và xử lý lỗi thường gặp, cùng tham khảo ngay nhé. 

Google Docs MCP với Claude Code là gì?

Sự kết hợp giữa Claude Code và Google Docs MCP cho phép lập trình viên đọc, phân tích và cập nhật tài liệu Google Docs trực tiếp ngay trong cửa sổ Terminal theo thời gian thực. Nhờ đó, bạn không còn phải chuyển đổi qua lại giữa trình duyệt và màn hình làm việc.

Để áp dụng thành công cách tích hợp Google Docs MCP với Claude Code, hãy cùng tìm hiểu nguyên lý hoạt động và những lợi ích thực tế mà giải pháp này mang lại ngay dưới đây.

Khái niệm Model Context Protocol (MCP) và cơ chế kết nối với Google Docs

Model Context Protocol (MCP) do Anthropic phát triển. Giao thức này giải quyết bài toán kết nối giữa các mô hình ngôn ngữ lớn (LLM) và các nguồn dữ liệu bên ngoài. Bạn có thể hình dung MCP giống như một cổng kết nối USB-C chuẩn hóa cho AI. Thay vì mỗi ứng dụng phải tự viết mã API riêng biệt, MCP tạo ra một phương thức giao tiếp chung giữa AI Client (Claude Code) và MCP Server. 

Hiện nay, Google cung cấp giải pháp dưới dạng Remote MCP Server chính thức cho Google Docs tại địa chỉ https://docsmcp.googleapis.com/mcp/v1. Server này vận hành dựa trên cơ chế truyền tải Streamable HTTP và giao thức xác thực OAuth 2.0.

Khi bạn đưa ra một câu lệnh bằng ngôn ngữ tự nhiên trong Claude Code (ví dụ: “Hãy đọc tài liệu kế hoạch dự án”), quy trình xử lý diễn ra qua 5 bước tiêu chuẩn: 

• Gửi yêu cầu: Người dùng nhập prompt vào Claude Code để thực hiện tác vụ với Google Docs.
• Khám phá và gọi công cụ: Claude Code gửi yêu cầu đến công cụ Google Docs MCP Server để lấy danh sách hàm hỗ trợ (như read_document hoặc batch_update), sau đó đóng gói lệnh thành cấu trúc JSON-RPC.
• Xác thực quyền qua OAuth 2.0: MCP Server kiểm tra token xác thực. Thông tin đăng nhập của người dùng hoàn toàn được bảo mật, không lưu trực tiếp trong AI Client.
• Tương tác với Google Docs API: Sau khi kiểm tra quyền truy cập, MCP Server truyền lệnh tới Google Docs REST API để xử lý tài liệu.
• Trả kết quả về ngữ cảnh AI: MCP Server chuyển đổi dữ liệu thô (Document Object Model) thành định dạng Plain Text hoặc Markdown giữ nguyên cấu trúc phân cấp, giúp Claude Code thấu hiểu ngữ cảnh để tiếp tục xử lý.

Lợi ích khi tích hợp Google Docs MCP vào Claude Code trong lập trình & quản lý dự án

Việc tích hợp Google Docs MCP với Claude Code mang lại những lợi ích vượt trội, giúp tối ưu hóa hiệu suất làm việc của lập trình viên và các quản lý dự án. 

• Thứ nhất, giúp tối ưu thời gian chuyển đổi ngữ cảnh

Lập trình viên không cần phải rời khỏi màn hình Terminal để chuyển sang trình duyệt web, tìm kiếm tài liệu rồi copy-paste thủ công. Bạn có thể yêu cầu AI đọc trực tiếp file PRD (Product Requirement Document) và khởi tạo khung mã nguồn (Boilerplate Code) ngay tại thư mục dự án. 

• Thứ hai, tiếp cận nguồn tài liệu dễ dàng

Trong các dự án phần mềm, yêu cầu kỹ thuật thường xuyên được cập nhật. Tích hợp trực tiếp giúp Claude Code luôn đọc được phiên bản mới nhất trên đám mây. Việc này cũng tránh được tình trạng viết mã dựa trên các bản thiết kế đã lỗi.

• Thứ ba, tự động hóa quản lý tài liệu kỹ thuật

AI có thể tự động tổng hợp các đoạn mã mới, chuyển đổi thành tài liệu hướng dẫn và cập nhật ngược trở lại file Google Docs thông qua các lệnh.

• Cuối cùng, bảo đảm được an toàn và phân quyền dữ liệu

Google Docs MCP kế thừa trọn vẹn cơ chế quản trị quyền của tài khoản Google. AI Client chỉ có thể đọc hoặc sửa những tài liệu mà người dùng đã cấp quyền truy cập cụ thể qua OAuth 2.0.

Cần chuẩn bị gì trước khi tích hợp Google Docs MCP?

Để quá trình tích hợp Google Docs MCP diễn ra thuận lợi, bạn cần chuẩn bị đầy đủ các tài khoản, môi trường lập trình và nền tảng kết nối, cụ thể như sau:

Tài khoản & quyền truy cập

• Tài khoản Anthropic: Đã đăng ký và có hỗ trợ thanh toán (Claude Pro, Max hoặc gói API khả dụng) để cấp quyền cho mô hình hoạt động.
• Tài khoản Google: Tài khoản cá nhân hoặc Google Workspace có chứa các tài liệu Google Docs mà bạn muốn kết nối và thao tác.

Môi trường phát triển phần mềm 

• Node.js: Đã cài đặt phiên bản từ 18.x trở lên trên máy tính.
• Ngôn ngữ lập trình: Kiến thức cơ bản về Python hoặc TypeScript (tùy thuộc vào thư viện và cổng trung gian bạn lựa chọn triển khai).

Nền tảng kết nối 

• Khóa API (API Key): Tạo và lấy API Key từ nền tảng quản lý xác thực trung gian (ví dụ: Composio API Key).
• Cấu hình môi trường (.env): Chuẩn bị sẵn tệp .env chứa các thông tin cấu hình cần thiết, tối thiểu gồm:
  • COMPOSIO_API_KEY
  • USER_ID

Hướng dẫn cách tích hợp Google Docs MCP với Claude Code

Google Docs MCP cho phép Claude Code kết nối trực tiếp với Google Docs để đọc nội dung, phân tích tài liệu và thực hiện một số thay đổi theo yêu cầu.

Google hiện cung cấp Google Docs MCP Server từ xa dưới dạng Developer Preview. Để sử dụng, Claude Code sẽ kết nối đến máy chủ MCP của Google thông qua Streamable HTTP và xác thực bằng OAuth 2.0.

Dưới đây là hướng dẫn từng bước để thiết lập kết nối này.

Trước khi tích hợp Google Docs MCP

Trước khi tích hợp Google Docs MCP với Claude Code, hãy đảm bảo bạn đã hoàn tất các yêu cầu sau:

• Tài khoản Google: Có quyền truy cập và chỉnh sửa tài liệu Google Docs cần làm việc.
• Google Workspace Developer Preview Program: Đăng ký tham gia chương trình để được sử dụng Google Docs MCP trong giai đoạn thử nghiệm.
• Google Cloud Project: Tạo hoặc sử dụng một dự án trên Google Cloud và bật Google Docs API.
• Claude Code: Cài đặt Claude Code trên máy tính và đăng nhập vào tài khoản của bạn.
• Xác thực Google: Thiết lập quyền xác thực để Claude Code có thể kết nối và làm việc với tài khoản Google.

Tạo OAuth Client trên công cụ Google Cloud 

Để thiết lập OAuth Client, bạn cần thực hiện lần lượt 03 bước dưới đây. 

• Bước 1: Tạo và cấu hình Project trên Google Cloud

Truy cập vào giao diện trang chủ Google Cloud Console. Tạo một Dự án mới (New Project) hoặc chọn dự án hiện có của bạn. Vào API & Services (API & Dịch vụ) >> chọn Library (Thư viện).

Tìm và bật Google Docs API (hoặc Google Drive API tùy thuộc vào phạm vi công cụ bạn cần dùng).

Tìm Google Docs API, nhấp vào và chọn Enable (Bật). 

•  Bước 2: Cấu hình Màn hình đồng ý OAuth (OAuth Consent Screen)

Từ menu bên trái, bạn cần nhấp chọn API & Services >> chọn OAuth consent screen. 

Sau đó, bạn chọn Get started (Bắt đầu tạo).

Điền các thông tin bắt buộc:

• App name: Nhập tên ứng dụng của bạn (ví dụ: Claude Code Docs MCP).
• User support email: Nhập thông tin email của bạn.

Sau đó, chọn Next (Tiếp tục), chọn loại người dùng là External (Bên ngoài) hoặc Internal (Nội bộ) tùy thuộc vào tổ chức Google Workspace của bạn.

Phần tiếp bạn hãy nhập Contact information ( Nhập email liên hệ).

Nhấn Create qua các phần Scope (Phạm vi) và Test users (Người dùng thử nghiệm) cho đến khi hoàn tất.

• Bước 3: Tạo OAuth Client ID

Bạn truy cập vào mục Credentials >> nhấp Create Credentials >> vào mục OAuth client ID).

Chọn loại ứng dụng (Application type): Chọn Web application (tùy thuộc vào cách cấu hình MCP client của bạn, thường dùng Desktop app/Web application).

Nhập Name cho OAuth Client (ví dụ: claude-code-docs-mcp) >> nhấn Create (Tạo).

Hộp thoại xuất hiện hiển thị Client ID và Client Secret. Hãy sao chép và lưu lại hai thông tin này một cách bảo mật. 

**Lưu ý: Client Secret là thông tin bảo mật. Không đăng công khai hoặc lưu trực tiếp vào Git repository.

Lấy thông tin Google Docs MCP Server 

Google cung cấp sẵn một MCP Server để Claude Code kết nối đến Google Docs. 

Thông tin kết nối như sau: 

Bạn không cần tự xây dựng MCP Server và chỉ cần cấu hình Claude Code kết nối đến địa chỉ MCP Server mà Google cung cấp. 

Thực hiện tích hợp Google Docs MCP với Claude Code

Sau khi tạo OAuth Client trên Google Cloud, bạn có thể kết nối Google Docs MCP với Claude. Theo hướng dẫn của Google, quá trình này được thực hiện bằng cách thêm Google Docs MCP dưới dạng Custom Connector trong Claude. 

• Bước 1: Mở phần Connectors trong công cụ Claude 

Đăng nhập vào Claude.ai hoặc mở Claude Desktop. Sau đó, truy cập Settings >> Connectors.  Nếu sử dụng tài khoản tổ chức, mục này có thể nằm trong Admin settings >> Connectors. 

• Bước 2: Thêm Custom Connector 

Trong phần Connectors, chọn Add >> chọn Add custom connector.

• Bước 3: Nhập thông tin Google Docs MCP 

Tại phần thông tin kết nối, nhập các nội dung Google Docs MCP  đã lấy phần trên. Trong đó, Remote MCP server URL là địa chỉ máy chủ Google Docs MCP do Google cung cấp. Bạn không cần tự tạo địa chỉ này. 

• Bước 4: Nhập thông tin OAuth

Tiếp theo, mở phần Advanced settings.

Tại đây, nhập hai thông tin bạn đã nhận được khi tạo OAuth Client trên Google Cloud:

1. OAuth Client ID
2. OAuth Client Secret

Sau khi nhập đầy đủ, kiểm tra lại thông tin và nhấp Add để hoàn tất việc thêm Google Docs MCP vào Claude.

• Bước 5: Hoàn tất kết nối

Sau khi thêm thành công, Claude sẽ sử dụng thông tin OAuth để xác thực với Google Docs MCP.

Sau khi xác thực thành công, Claude có thể kết nối với Google Docs MCP và sử dụng các công cụ mà máy chủ cung cấp.

Claude Code sử dụng Google Docs MCP 

Sau khi tích hợp, Claude Code có thể sử dụng Google Docs MCP để thực hiện các thao tác với tài liệu. 

• Đọc nội dung Google Docs 

Ví dụ: Đọc tài liệu này và cho tôi biết tài liệu đang có những H1, H2 và H3 nào.

• Cập nhật Google Docs

Ví dụ, bạn có thể yêu cầu Claude Code thực hiện một số thay đổi về nội dung hoặc định dạng. 

Các lỗi thường gặp khi tích hợp Google Docs MCP và cách xử lý

Trong quá trình thực hiện cách tích hợp Google Docs MCP với Claude Code, không ít người dùng gặp phải những sự cố ngoài ý muốn. Các lỗi này thường xuất phát từ việc cấu hình sai lệch quyền hạn, hết hạn token xác thực hoặc đường dẫn tệp không chính xác. Phần dưới đây sẽ tổng hợp 03 nhóm lỗi phổ biến nhất cùng các bước xử lý cụ thể giúp bạn khắc phục sự cố nhanh chóng.

Lỗi OAuth Client Unverified hoặc Access Blocked

Dấu hiệu: Khi bấm vào link xác thực trên trình duyệt, Google hiển thị màn hình đỏ với thông báo “Access blocked: App has not completed the Google verification process” hoặc “Sign in with Google disabled for this app”.

Nguyên nhân:

• Dự án Google Cloud của bạn đang ở trạng thái Testing nhưng tài khoản Email bạn dùng để đăng nhập lại chưa được thêm vào danh sách tài khoản thử nghiệm (Test Users).
• Bạn chọn nhầm phạm vi truy cập (Scopes) mang tính chất nhạy cảm (Sensitive Scopes) mà không khai báo đúng thông tin trên OAuth Consent Screen.

Cách xử lý:

• Truy cập lại trang console.cloud.google.com >> chọn dự án của bạn.
• Điều hướng tới APIs & Services >> OAuth consent screen.

• Cuộn xuống phần Test users, nhấn + ADD USERS.
• Nhập chính xác địa chỉ Gmail mà bạn đang dùng để đăng nhập và lưu lại.
• Kiểm tra mục Publishing status. Bạn không cần nhấn “Publish App” (vì ứng dụng cá nhân không cần Google duyệt chính thức), chỉ cần đảm bảo email của bạn đã nằm trong danh sách Test Users là có thể đăng nhập bình thường thông qua nút “Advanced” > “Go to App (unsafe)”.

Lỗi Invalid Credentials hoặc Refresh Token hết hạn

Dấu hiệu: Claude Code báo lỗi Error: invalid_grant, Token has been expired or revoked, hoặc không thể thực thi bất kỳ hàm nào của Google Docs dù trước đó đã kết nối thành công.

Nguyên nhân:

• Trong giai đoạn ứng dụng GCP ở trạng thái Testing, các Refresh Token được Google cấp chỉ có thời hạn sử dụng tối đa trong 7 ngày. Sau 7 ngày, token này sẽ tự động bị hủy bỏ và bạn bắt buộc phải cấp quyền lại từ đầu.
• Tệp credentials.json đã bị xóa, di chuyển sang vị trí khác hoặc thay đổi nội dung.

Cách xử lý:

• Xóa tệp đệm chứa token xác thực đã cũ trên máy tính của bạn. Tệp này thường nằm cùng thư mục cài đặt MCP Server hoặc trong thư mục người dùng cá nhân (ví dụ: ~/.config/gdocs-mcp/token.json hoặc ~/.gdocs-token.json).
• Mở cửa sổ Claude Code và chạy lệnh làm mới xác thực hoặc yêu cầu Claude đọc lại một file Google Docs bất kỳ.
• MCP Server sẽ nhận diện tệp token không còn tồn tại và tự động tạo OAuth URL mới, sau đó mở đường dẫn này trên trình duyệt để bạn thực hiện xác thực lại. Bạn chỉ cần thực hiện lại thao tác đăng nhập và cấp quyền để nhận Refresh Token mới cho 7 ngày tiếp theo.

Lỗi không tìm thấy file hoặc thiếu quyền truy cập Google Docs

Dấu hiệu: Claude Code trả về thông báo, Requested entity was not found hoặc 403 Permission Denied khi bạn cung cấp một Document ID hoàn toàn có thật.

Nguyên nhân:

• Bạn cung cấp sai chuỗi Document ID (sao chép thiếu ký tự hoặc lấy nhầm ID của thư mục Google Drive).
• Tệp Google Docs đó thuộc về một tài khoản Gmail khác và chưa được chia sẻ quyền truy cập cho tài khoản Google mà bạn dùng để liên kết MCP.
• OAuth Consent Screen của bạn chỉ được cấp quyền documents.readonly nên khi bạn ra lệnh cho Claude Code tạo hoặc chỉnh sửa file, hệ thống sẽ chặn lệnh do thiếu quyền ghi.

Cách xử lý:

• Kiểm tra ID tệp: Mở file Google Docs trên trình duyệt, nhìn vào thanh địa chỉ URL và sao chép chính xác đoạn mã nằm giữa /d/ và /edit.
• Kiểm tra quyền tài khoản: Đảm bảo tệp Google Docs đó đã được phân quyền “Viewer” (đối với lệnh đọc) hoặc “Editor” (đối với lệnh sửa) cho địa chỉ email liên kết MCP của bạn.
• Cập nhật Scopes: Nếu lỗi do thiếu quyền ghi, hãy truy cập Google Cloud Console > OAuth consent screen >> Edit App >> Thêm scope (https://www.googleapis.com/auth/documents) và thực hiện lại bước đăng nhập OAuth để cấp bổ sung quyền cho Claude Code.

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

1: Google Docs MCP có phải là Google Drive Connector chính thức của Claude không?

Không. Google Drive Connector là tính năng tích hợp do Anthropic phát triển, được cung cấp trực tiếp trên giao diện web của Claude dành cho người dùng có gói trả phí. Trong khi đó, Google Docs MCP là một giao thức mở, cho phép bạn kết nối trực tiếp công cụ dòng lệnh Claude Code (CLI) với các API chuyên sâu của Google Docs. 

Điểm vượt trội của giải pháp MCP là nó cho phép thực hiện các thao tác ghi, chỉnh sửa văn bản tại chỗ (In-place edit) và tạo tài liệu mới một cách linh hoạt. Đây là điều mà Connector mặc định trên giao diện web chưa hỗ trợ đầy đủ.

2: Có bắt buộc phải tạo Google Cloud Project để dùng Google Docs MCP không?

Có. Do Google quy định mọi truy cập lập trình vào hệ sinh thái Google Workspace bắt buộc phải thông qua các cổng API có định danh, bạn phải khởi tạo một dự án trên Google Cloud Console để lấy tệp credentials.json (OAuth Client ID). 

Tệp này đóng vai trò quan trọng để Google xác nhận rằng Claude Code đang truy cập dữ liệu dưới sự cho phép hợp pháp của bạn. Quá trình tạo Google Cloud Project là hoàn toàn miễn phí và không yêu cầu bạn phải nhập thẻ thanh toán quốc tế đối với các hạn ngạch sử dụng cơ bản.

3: Google Docs MCP có thể chỉnh sửa trực tiếp tài liệu Google Docs hiện có không?

Có. Thông qua các API tương tác cấu trúc văn bản của Google Docs, Claude Code có thể thêm các đoạn văn bản mới, chèn bảng biểu, cập nhật danh sách gạch đầu dòng hoặc thay thế các chuỗi ký tự trong một tệp Google Docs đang tồn tại mà không làm mất đi các định dạng ban đầu của tài liệu. Bạn hoàn toàn không cần phải tạo ra một file sao chép mới mỗi khi muốn chỉnh sửa nội dung.

Lời kết 

Hy vọng bài viết này đã mang đến cho bạn cái nhìn toàn diện và chi tiết nhất về cách tích hợp Google Docs MCP với Claude Code từ A-Z. Và từ giờ, các lập trình viên và quản lý dự án tại Việt Nam có thể dễ dàng đọc tóm tắt, khởi tạo, cập nhật văn bản hay trích xuất tài liệu PRD trực tiếp từ Terminal mà không còn tốn thời gian chuyển đổi giữa các cửa sổ làm việc.

Ngoài ra, nếu trong quá trình thực hiện bạn gặp các vấn đề khó khăn trong thao tác, có thể liên hệ với GCS Việt Nam để nhận sự hỗ trợ kịp thời.

• Fanpage: GCS – Google Cloud Solutions 

• Hotline: 024.9999.7777