本指南說明如何將 Notion MCP Server 接到 Claude Code。完成後，Claude 可在明確授權的範圍內搜尋、讀取與更新 Notion 頁面。

前置準備

• 安裝 Claude Code（CLI、VS Code Extension 或 Desktop App）。
• 安裝 Node.js，並確認 npx 可用。
• 準備一個 Notion 帳號與要授權的頁面。

1. 建立 Notion Integration

1. 前往 Notion Integrations。
2. 選擇 New integration。
3. 填寫 Integration 名稱，例如 Claude MCP。
4. 選擇要連接的 Workspace。
5. 建立後複製 Internal Integration Secret。

Token 只會顯示一次，請使用密碼管理器保存；不要提交到 Git 或貼到公開文件。

2. 設定 Claude Code 的 MCP Server

在要使用 MCP 的專案目錄建立設定檔：

mkdir -p .claude

建立 .claude/settings.json：

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

將 <YOUR_NOTION_TOKEN> 替換為 Integration Secret。設定檔若會進入版本控制，應改用不提交的本機設定或環境變數管理 token。

3. 授權 Notion 頁面

Integration 建立後不會自動取得所有頁面權限：

1. 開啟要讓 Claude 存取的 Notion 頁面。
2. 點擊右上角 ⋯ → Connections。
3. 搜尋並加入剛建立的 Integration。

授權父頁面後，通常可一併存取其子頁面；仍應只授權實際需要的範圍。

4. 重啟 Claude Code

設定完成後重新啟動 Claude Code，讓 MCP Server 載入：

• CLI：退出後重新執行 claude。
• VS Code Extension：重新開啟 VS Code，或執行 Reload Window。

Notion API 的限制

• Status 屬性的分組設定通常需要在 Notion UI 調整。
• Calendar、Board、Gallery 等 database views 通常需要在 Notion UI 建立或修改。
• 單一 Rich Text 區塊有長度限制，長內容需拆成多個區塊。
• 批次 append children 時，單次請求的區塊數量有限制。

檔案結構

your-project/
├── .claude/
│   └── settings.json
└── ...