·

Notion MCP với Claude Code CLI and VS Code

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

Claude Code (CLI của Anthropic chạy trực tiếp trong terminal, và extension chạy trong VS Code) là một trong những agentic coding tool (công cụ code theo hướng agentic) hỗ trợ MCP mượt nhất hiện nay, vì bản thân Claude Code được thiết kế để dùng tool calling như một phần cốt lõi trong vòng lặp làm việc. Khi ghép với Notion MCP, bạn có một trợ lý có thể vừa đọc code trong repo, vừa đọc/ghi tài liệu trên Notion trong cùng một phiên làm việc — không cần chuyển tab, không cần copy-paste. Bài này hướng dẫn cách cài đặt, và quan trọng hơn, cách prompt đúng để Claude Code tạo ra tài liệu Notion sạch, đúng cấu trúc, không bị "AI-slop" (nội dung AI sinh ra hời hợt, dư thừa).

Cài Đặt Và Kết Nối Notion MCP Với Claude Code

Claude Code quản lý MCP server thông qua file cấu hình hoặc CLI command claude mcp add. Cách nhanh nhất để thêm Notion MCP:

claude mcp add notionApi \
  --env "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_xxx\", \"Notion-Version\": \"2022-06-28\"}" \
  -- npx -y @notionhq/notion-mcp-server

Hoặc nếu bạn muốn quản lý bằng file cấu hình project-level (.mcp.json ở root repo, phù hợp khi muốn chia sẻ config cho cả team qua git):

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

Chú ý: nên dùng biến môi trường (${NOTION_TOKEN}) thay vì hardcode token thẳng vào file commit lên git — kể cả với repo private, đây vẫn là thói quen bảo mật cơ bản. Đặt NOTION_TOKEN trong .env local hoặc secret manager của CI, không commit file chứa token thật.

Sau khi thêm, chạy claude mcp list để xác nhận server đã kết nối và status: connected. Nếu dùng VS Code extension, mở Command Palette, tìm "Claude Code: MCP Servers" để xem trạng thái tương tự dưới dạng UI — tiện khi bạn không muốn rời khỏi editor để check terminal.

Mẹo: Chạy thử một lệnh đọc đơn giản ngay sau khi cài, ví dụ "Tìm page 'Onboarding' trong Notion của tôi", trước khi giao việc phức tạp. Nếu bước này lỗi, gần như chắc chắn là do token hoặc quyền share, chưa liên quan gì đến prompt của bạn.

Sinh Tài Liệu Kỹ Thuật Và Trang Requirements Từ Code Và Spec

Đây là use case mang lại giá trị rõ nhất cho senior engineer: bạn vừa code xong một feature, và muốn có ngay một trang tài liệu mô tả kiến trúc, decision, trade-off — thay vì để việc viết doc trôi qua vì "để sau".

Ví dụ prompt thực tế trong Claude Code, sau khi bạn đã ở trong repo và Claude đã đọc qua các file liên quan:

Đọc toàn bộ code trong src/services/order-service (bao gồm cả test),
sau đó tạo một page mới trong Notion database "Technical Docs" với:
- Title: "Order Service - Architecture Overview"
- Một section mô tả luồng xử lý order từ lúc nhận request tới khi publish event
- Một bảng liệt kê các API endpoint, method, và mô tả ngắn
- Một section "Known Trade-offs" liệt kê các quyết định kỹ thuật có đánh đổi (ví dụ eventual consistency)
Không cần diễn giải dài dòng, viết ngắn gọn, đúng trọng tâm cho một senior engineer đọc.

Điểm mấu chốt: prompt trên chỉ rõ cấu trúc mong muốn (title, các section, bảng) — nếu bạn chỉ nói "viết doc cho tôi", Claude sẽ tự chọn cấu trúc, và kết quả thường lan man hoặc thiếu phần bạn cần. Với requirements page (mô tả yêu cầu sản phẩm) từ spec code có sẵn, cách làm tương tự nhưng đảo hướng: bạn yêu cầu Claude đọc trang Notion cũ, đối chiếu với code hiện tại, rồi chỉ ra phần nào đã lỗi thời.

Mẹo: Luôn thêm câu "trước khi tạo page, tóm tắt cho tôi outline dự kiến để tôi duyệt" vào prompt khi tạo tài liệu quan trọng. Việc review outline trước khi Claude ghi vào Notion giúp tránh phải sửa lại một page đã tạo — sửa outline dễ hơn nhiều so với sửa page đã có nội dung.

Đọc Và Cập Nhật Notion Database Từ Terminal

Ngoài việc tạo tài liệu, một use case rất thực dụng là dùng Claude Code như một "CLI cho Notion database" — đặc biệt hữu ích khi bạn đang trong terminal xử lý task và không muốn mở browser.

Ví dụ đọc database task tracker:

Query database "Sprint Board" trong Notion, lấy các item có Assignee = "tôi"
và Status khác "Done", in ra dạng bảng gọn với Title, Status, Due Date.

Ví dụ cập nhật trạng thái sau khi merge PR:

Tôi vừa merge PR #482 fix bug liên quan tới "Refund flow throws 500".
Tìm task tương ứng trong database "Sprint Board" (có thể tên khác đôi chút),
cập nhật Status thành "Done" và thêm comment vào page với nội dung
"Fixed in PR #482, merged <ngày hôm nay>".

Cách làm này giúp bạn giữ database luôn cập nhật đúng thời điểm code được merge, thay vì dồn lại cuối ngày rồi quên mất chi tiết. Với các bạn dùng Claude Code kết hợp git hook hoặc slash command tuỳ biến, bạn có thể tự động hoá thêm — ví dụ tạo một custom slash command /close-task gói sẵn prompt trên để gọi nhanh bằng một lệnh.

Mẹo: Khi cập nhật property dạng "Select" hoặc "Status" trong Notion, luôn xác nhận trước với Claude tên option chính xác (ví dụ "Done" hay "Completed") — Notion không tự tạo option mới nếu bạn gõ sai tên, mà một số phiên bản MCP server sẽ tạo nhầm option trùng lặp, gây rác dữ liệu về sau.

Các Pattern Prompt Để Notion Được Format Sạch Và Có Cấu Trúc

Sau một thời gian dùng thực tế, có vài pattern prompt giúp giảm đáng kể tình trạng Claude tạo page Notion bị "rối format" — heading sai cấp, bullet lồng nhau lộn xộn, hoặc thiếu khoảng trắng giữa section.

Pattern 1 — Chỉ định rõ heading level: thay vì nói "chia thành các phần", hãy nói rõ "dùng Heading 2 cho mỗi phần chính, Heading 3 cho phần con" — Claude Code map trực tiếp sang block type heading_2, heading_3 của Notion.

Pattern 2 — Yêu cầu callout cho phần quan trọng: Notion có block callout (khung nổi bật có icon) rất hợp để nhấn mạnh cảnh báo hoặc lưu ý. Prompt ví dụ: "đưa phần rủi ro vào một callout block với icon ⚠️".

Pattern 3 — Giới hạn độ dài mỗi block text: vì Notion API giới hạn ký tự trong mỗi rich text block, với đoạn văn rất dài, yêu cầu Claude "chia đoạn dài thành các đoạn nhỏ hơn 3-4 câu" giúp tránh lỗi request bị từ chối do vượt limit.

Pattern 4 — Table thay vì bullet lồng nhiều cấp: khi có dữ liệu dạng so sánh (API, config, version...), luôn yêu cầu dùng table block thay vì bullet — table trong Notion dễ đọc và dễ maintain hơn nhiều so với bullet lồng 3-4 cấp.

Format lại phần "So sánh các phương án cache" trong page vừa tạo thành
một table với 3 cột: Phương án, Ưu điểm, Nhược điểm. Không dùng bullet lồng nhau.

Mẹo: Nếu page tạo ra bị lỗi format nhẹ (ví dụ heading sai cấp), đừng yêu cầu Claude "viết lại từ đầu" — hãy yêu cầu nó đọc lại page hiện tại, chỉ sửa các heading sai cấp, giữ nguyên phần nội dung đã đúng. Việc này tiết kiệm token và tránh rủi ro Claude viết lại làm mất nội dung tốt đã có.

Mẹo Thực Chiến Khi Dùng Notion MCP Trong Claude Code

  • Luôn làm việc trên một page/database "sandbox" khi test prompt mới, trước khi áp dụng lên tài liệu thật của team.
  • Tận dụng CLAUDE.md trong repo để ghi sẵn quy ước Notion của team (ví dụ tên database chuẩn, format tiêu đề page) — Claude Code sẽ tự đọc file này và áp dụng nhất quán qua các phiên làm việc khác nhau.
  • Với VS Code extension, dùng panel MCP để xem log request/response khi cần debug lỗi tool calling — nhanh hơn nhiều so với đoán qua câu trả lời text.
  • Định kỳ review lại các page do AI tạo trong 1-2 tuần đầu để hiệu chỉnh prompt pattern, sau đó lưu các pattern hoạt động tốt thành template trong CLAUDE.md.

Mẹo: Ghi các prompt Notion mẫu đã hoạt động tốt (tạo doc, update status, sinh release note) thành một section riêng trong CLAUDE.md của repo. Đây gần như là "runbook" giúp mọi engineer trong team dùng Claude Code theo cùng một chuẩn, giảm thời gian dò lại prompt từ đầu.

Tiếp Notion MCP với OpenCode