·

Notion MCP với Gemini CLI

Cài đặt Notion MCP trong Gemini CLI để AI agent có thể đọc và viết trang, database ngay trong trình soạn thảo.

Gemini CLI là agentic tool của Google chạy trong terminal, tận dụng context window (cửa sổ ngữ cảnh) rất lớn của model Gemini — một lợi thế rõ rệt khi làm việc với Notion, nơi requirement thường rải rác trên nhiều page dài. Bài này hướng dẫn cách kết nối Notion MCP vào Gemini CLI, cách khai thác context window lớn để phân tích requirement trải trên nhiều page cùng lúc, và so sánh thẳng thắn chất lượng output giữa Gemini CLI và Claude Code khi cùng làm một task Notion — để bạn biết nên chọn công cụ nào cho từng loại việc.

Cài Đặt Và Kết Nối Notion MCP Với Gemini CLI

Gemini CLI cấu hình MCP server qua file settings.json (tại ~/.gemini/settings.json cho global, hoặc .gemini/settings.json trong project để cấu hình riêng cho repo đó). Cấu trúc gần giống chuẩn MCP phổ biến:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer $NOTION_TOKEN\", \"Notion-Version\": \"2022-06-28\"}"
      },
      "timeout": 30000
    }
  }
}

Sau khi lưu file, khởi động lại Gemini CLI (gemini), rồi gõ lệnh:

/mcp list

để xem trạng thái kết nối. Nếu server hiện kết nối thành công, bạn sẽ thấy danh sách tool Notion MCP xuất hiện — thử gõ /mcp desc notionApi (tuỳ phiên bản) để xem chi tiết từng tool và tham số.

Một điểm cần lưu ý riêng với Gemini CLI: vì Google có chính sách rate limit theo API key/project khá chặt ở tier miễn phí, khi bạn dùng đồng thời nhiều tool call Notion trong một phiên dài, có thể gặp lỗi quota trước cả khi gặp rate limit của Notion. Nếu việc này xảy ra thường xuyên, cân nhắc dùng API key trả phí (Gemini API tier có trả phí) hoặc giảm tần suất gọi tool liên tục.

Mẹo: Đặt NOTION_TOKEN trong biến môi trường shell (export NOTION_TOKEN=ntn_xxx trong .zshrc/.bashrc) thay vì viết trực tiếp trong settings.json, ngay cả khi file đó không nằm trong repo. Thói quen này giúp bạn đổi token (ví dụ khi rotate định kỳ) mà không phải sửa nhiều nơi.

Truy Vấn Notion Database Và Trích Xuất Requirement Trong Gemini CLI

Lợi thế lớn nhất của Gemini CLI khi làm việc với Notion là context window lớn — bạn có thể yêu cầu nó đọc nhiều page/database cùng lúc mà không lo tràn context như với model có context ngắn hơn. Đây là use case rất hợp cho việc phân tích requirement khi thông tin rải rác trên nhiều nơi.

Ví dụ prompt truy vấn kết hợp nhiều database:

Đọc database "Product Requirements" và database "Customer Feedback" trong Notion.
Với feature "Multi-currency checkout", tổng hợp:
1. Tất cả requirement đã ghi liên quan (từ Product Requirements)
2. Tất cả feedback khách hàng liên quan (từ Customer Feedback)
3. Chỉ ra điểm nào feedback khách hàng CHƯA được phản ánh vào requirement hiện tại

Đây là dạng task mà việc có context window lớn thực sự tạo khác biệt — agent không cần tóm tắt từng phần rồi tóm tắt lại (mất thông tin qua nhiều lớp), mà có thể "nhìn" toàn bộ dữ liệu gốc một lần để so sánh đối chiếu.

Với truy vấn có điều kiện lọc phức tạp trên database, bạn có thể prompt trực tiếp bằng ngôn ngữ filter tự nhiên, ví dụ:

Query database "Bug Tracker", lấy các bug có Severity = "Critical" AND Status != "Closed"
AND Created date trong 30 ngày gần nhất, xuất ra bảng sort theo Created date giảm dần.

Gemini CLI sẽ chuyển yêu cầu này thành filter object đúng chuẩn Notion API (kết hợp điều kiện and, so sánh ngày) — bạn không cần biết cú pháp filter JSON của Notion.

Mẹo: Khi truy vấn nhiều database cùng lúc, luôn nêu rõ tên database chính xác (copy từ Notion) trong prompt đầu tiên của phiên làm việc. Việc này giúp giảm số lần agent phải gọi tool search để "đoán" đúng database, tiết kiệm cả thời gian và số lượt gọi tool.

Ví Dụ Thực Tế: Xây Dựng Feature Matrix Từ Các Page Notion Rời Rạc

Một bài toán rất thường gặp với product/engineering team: thông tin về các feature đã có nằm rải rác trên nhiều page (spec cũ, page họp, page changelog) mà không ai có thời gian tổng hợp lại thành một bảng so sánh (feature matrix) mạch lạc. Đây là nơi context window lớn của Gemini CLI phát huy tác dụng rõ nhất.

Quy trình gợi ý:

Bước 1 — Yêu cầu agent quét toàn bộ page liên quan:

Tìm tất cả page trong Notion có chứa từ khoá "export" hoặc "báo cáo" trong workspace
"Product Team", đọc nội dung từng page.

Bước 2 — Yêu cầu tổng hợp thành matrix:

Từ các page vừa đọc, tạo một feature matrix dạng table với các cột:
Feature name, Platform (Web/Mobile/API), Status hiện tại, Page nguồn (link),
Ghi chú (nếu thông tin giữa các page mâu thuẫn nhau, ghi rõ mâu thuẫn đó).
Sau đó tạo page mới "Export Features - Matrix" trong database "Technical Docs" với table này.

Phần "ghi rõ mâu thuẫn" trong bước 2 rất quan trọng — với dữ liệu rải rác từ nhiều nguồn cũ, khả năng cao có thông tin đã lỗi thời hoặc mâu thuẫn nhau; một agent tốt phải nêu ra mâu thuẫn để người review quyết định, không nên tự chọn một phiên bản rồi im lặng bỏ qua phiên bản khác.

Mẹo: Với feature matrix quan trọng dùng để ra quyết định (roadmap, sizing), luôn yêu cầu agent trích dẫn nguồn (link page cụ thể) cho từng dòng dữ liệu. Điều này biến matrix từ "AI tự nói" thành "có thể verify được" — yếu tố sống còn khi dữ liệu ảnh hưởng tới quyết định kinh doanh.

So Sánh Kết Quả Notion MCP Giữa Gemini CLI Và Claude Code

Sau khi thực chiến cả hai công cụ trên cùng loại task Notion, có vài khác biệt rõ rệt đáng lưu ý khi bạn chọn công cụ cho từng tình huống:

Về khả năng xử lý nhiều nguồn dữ liệu lớn cùng lúc: Gemini CLI có lợi thế nhờ context window lớn hơn, phù hợp khi task cần "đọc hết" nhiều page dài trước khi tổng hợp — ví dụ task feature matrix ở trên. Claude Code với context window nhỏ hơn có thể cần agent tự chia nhỏ, đọc tuần tự và tóm tắt dần — chậm hơn nhưng đôi khi lại buộc agent phải chọn lọc thông tin quan trọng tốt hơn (vì phải tóm tắt sớm).

Về độ chính xác tool calling (chọn đúng tool, đúng tham số): cả hai đều xử lý tốt các tool phổ biến (search, retrieve, query database), nhưng với các thao tác ghi phức tạp (append block lồng nhiều cấp, table block), Claude Code thường cho kết quả format sạch hơn và ít lỗi cấu trúc block hơn trong trải nghiệm thực tế — có thể do Claude được huấn luyện tốt cho các workflow tool-use dài và có structured output nhất quán.

Về tốc độ và chi phí: Gemini CLI có tier miễn phí generous hơn cho việc thử nghiệm, phù hợp khi bạn mới học và muốn test nhiều prompt pattern mà không lo chi phí. Claude Code phù hợp hơn cho công việc production cần độ tin cậy cao và ổn định.

Kết luận thực dụng: dùng Gemini CLI cho các task "đọc nhiều, phân tích tổng hợp" (feature matrix, đối chiếu requirement); dùng Claude Code cho các task "viết nhiều, cần format chính xác" (sinh tài liệu kỹ thuật chi tiết, tạo page có cấu trúc phức tạp). Không có công cụ nào thắng tuyệt đối — chọn theo bản chất công việc.

Mẹo: Nếu team bạn dùng cả hai công cụ, hãy thống nhất quy ước: Gemini CLI cho phase "research/tổng hợp", Claude Code cho phase "viết tài liệu chính thức". Tránh tình trạng mỗi người dùng công cụ khác nhau cho cùng loại việc, dẫn đến tài liệu Notion có style không đồng nhất giữa các page.

Tiếp Notion MCP với Cursor