Better Notion MCP

🚀 Better Notion MCP

專為AI智能體優化的、以Markdown為先的Notion MCP服務器

🚀 快速開始

在使用之前，你需要獲取你的Notion令牌：訪問 https://www.notion.so/my-integrations → 創建集成 → 複製令牌 → 與集成共享頁面。

✨ 主要特性

為何是 “Better” ？

它擁有7個基於大型操作的工具，將Notion的28個以上的REST API端點整合為針對AI智能體優化的複合操作。

與官方Notion MCP服務器對比

📦 安裝指南

NPX（推薦）

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "better-notion": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NOTION_TOKEN", "n24q02m/better-notion-mcp:latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

📚 詳細文檔

工具概述

7個大型工具，擁有30多個操作：

• 複合操作：組合操作（例如，一次調用即可創建頁面、內容和屬性）
• 自動分頁：透明處理大型數據集
• 批量操作：高效處理多個項目
• 智能搜索：在數據庫查詢中自動檢測最佳匹配

限制

支持的塊類型（Markdown轉換）：

• ✅ 標題（H1 - H3）、段落、列表（無序列表/有序列表）
• ✅ 代碼塊、引用、分隔線
• ✅ 內聯格式（粗體、斜體、代碼、刪除線、鏈接）

不支持的塊類型：

• ❌ 表格、摺疊塊、標註、列
• ❌ 數據庫、嵌入內容、圖像、文件
• ❌ 同步塊、模板

從源代碼構建

本項目使用 mise 進行工具版本管理。如果你沒有安裝mise，請參考 mise.jdx.dev。

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp

mise trust
mise install

pnpm install
pnpm build

uv venv
uv pip install pre-commit
uv run pre-commit install
uv run pre-commit run --all-file

前提條件：mise或Node.js 22+以及pnpm。

可用命令

pnpm dev                    # 運行開發服務器並自動重新加載
pnpm build                  # 構建項目
pnpm test                   # 運行測試
pnpm test:watch             # 以監視模式運行測試
pnpm test:coverage          # 運行測試並生成覆蓋率報告
pnpm check                  # 檢查格式、 linting和類型（Biome + TypeScript）
pnpm check:fix              # 自動修復格式和linting問題

貢獻代碼

歡迎貢獻代碼！請參考 CONTRIBUTING.md 瞭解：

• 開發工作流程（通過CI驗證）
• 提交規範（通過git鉤子強制執行）
• 測試和代碼質量標準

📄 許可證

本項目採用MIT許可證，請查看 LICENSE 瞭解詳情。

如果你覺得這個倉庫有用，請給它點個星！⭐