MCP Notion Server

🚀 Notion MCP Server

Notion MCP Server 是一個用於 Notion API 的服務器，它能讓大語言模型（LLM）與 Notion 工作空間進行交互。此外，該服務器採用 Markdown 轉換技術，在與大語言模型通信時減少上下文大小，優化令牌使用，使交互更加高效。

🚀 快速開始

以下文章詳細解釋了上述步驟：

• 英文版本：https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
• 日文版本：https://qiita.com/suekou/items/44c864583f5e3e6325d9

✨ 主要特性

該項目有以下特性：

• 支持大語言模型與 Notion 工作空間交互。
• 採用 Markdown 轉換技術，優化令牌使用。

📦 安裝指南

具體步驟

1. 創建 Notion 集成：
   • 訪問 Notion 集成頁面。
   • 點擊“New Integration”。
   • 為集成命名並選擇適當的權限（例如，“Read content”、“Update content”）。
2. 獲取密鑰：
   • 從你的集成中複製“Internal Integration Token”。
   • 此令牌將用於身份驗證。
3. 將集成添加到工作空間：
   • 在 Notion 中打開你希望集成訪問的頁面或數據庫。
   • 點擊右上角的“···”按鈕。
   • 點擊“Connections”按鈕，選擇你在步驟 1 中創建的集成。
4. 配置 Claude Desktop： 在 claude_desktop_config.json 文件中添加以下內容：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@kimjungyeol/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

或者

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

環境變量

• NOTION_API_TOKEN（必需）：你的 Notion API 集成令牌。
• NOTION_MARKDOWN_CONVERSION：設置為 "true" 以啟用實驗性的 Markdown 轉換。這可以在查看內容時顯著減少令牌消耗，但在嘗試編輯頁面內容時可能會導致問題。

命令行參數

• --enabledTools：以逗號分隔的要啟用的工具列表（例如 "notion_retrieve_page,notion_query_database"）。指定時，僅列出的工具可用。如果未指定，則啟用所有工具。

只讀工具示例（方便複製粘貼）：

node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments

💻 使用示例

基礎用法

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@kimjungyeol/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

高級用法

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

當 NOTION_MARKDOWN_CONVERSION 設置為 "true" 時，響應將轉換為 Markdown 格式（當 format 參數設置為 "markdown" 時），這使得響應更易於閱讀，並顯著減少令牌消耗。但是，由於此功能是實驗性的，在嘗試編輯頁面內容時可能會導致問題，因為轉換過程中會丟失原始結構。

你可以在每次請求時通過將 format 參數設置為 "json" 或 "markdown" 來控制格式：

• 僅查看內容時使用 "markdown" 以獲得更好的可讀性。
• 需要修改返回內容時使用 "json"。

📚 詳細文檔

故障排除

如果你遇到權限錯誤：

1. 確保集成具有所需的權限。
2. 驗證集成是否已被邀請到相關頁面或數據庫。
3. 確認令牌和配置是否已在 claude_desktop_config.json 中正確設置。

項目結構

項目採用模塊化方式組織，以提高可維護性和可讀性：

./
├── src/
│   ├── index.ts              # 入口點和命令行處理
│   ├── client/
│   │   └── index.ts          # 用於 API 交互的 NotionClientWrapper 類
│   ├── server/
│   │   └── index.ts          # MCP 服務器設置和請求處理
│   ├── types/
│   │   ├── index.ts          # 類型導出
│   │   ├── args.ts           # 工具參數接口
│   │   ├── common.ts         # 通用模式定義
│   │   ├── responses.ts      # API 響應類型定義
│   │   └── schemas.ts        # 工具模式定義
│   ├── utils/
│   │   └── index.ts          # 實用函數
│   └── markdown/
│       └── index.ts          # Markdown 轉換實用工具

目錄說明

• index.ts：應用程序入口點。解析命令行參數並啟動服務器。
• client/：負責與 Notion API 通信的模塊。
  • index.ts：NotionClientWrapper 類實現所有 API 調用。
• server/：MCP 服務器實現。
  • index.ts：處理從 Claude 接收的請求並調用適當的客戶端方法。
• types/：類型定義模塊。
  • index.ts：所有類型的導出。
  • args.ts：工具參數的接口定義。
  • common.ts：通用模式的定義（ID 格式、富文本等）。
  • responses.ts：Notion API 響應的類型定義。
  • schemas.ts：MCP 工具模式的定義。
• utils/：實用函數。
  • index.ts：如過濾啟用工具等函數。
• markdown/：Markdown 轉換功能。
  • index.ts：將 JSON 響應轉換為 Markdown 格式的邏輯。

工具

所有工具都支持以下可選參數：

• format（字符串，"json" 或 "markdown"，默認："markdown"）：控制響應格式。使用 "markdown" 以獲得人類可讀的輸出，使用 "json" 以編程方式訪問原始數據結構。注意：Markdown 轉換僅在 NOTION_MARKDOWN_CONVERSION 環境變量設置為 "true" 時有效。

1. notion_append_block_children

   • 向父塊追加子塊。
   • 必需輸入：
     • block_id（字符串）：父塊的 ID。
     • children（數組）：要追加的塊對象數組。
   • 返回：關於追加塊的信息。

2. notion_retrieve_block

   • 檢索特定塊的信息。
   • 必需輸入：
     • block_id（字符串）：要檢索的塊的 ID。
   • 返回：關於該塊的詳細信息。

3. notion_retrieve_block_children

   • 檢索特定塊的子塊。
   • 必需輸入：
     • block_id（字符串）：父塊的 ID。
   • 可選輸入：
     • start_cursor（字符串）：下一頁結果的遊標。
     • page_size（數字，默認：100，最大：100）：要檢索的塊數。
   • 返回：子塊列表。

4. notion_delete_block

   • 刪除特定塊。
   • 必需輸入：
     • block_id（字符串）：要刪除的塊的 ID。
   • 返回：刪除確認信息。

5. notion_retrieve_page

   • 檢索特定頁面的信息。
   • 必需輸入：
     • page_id（字符串）：要檢索的頁面的 ID。
   • 返回：關於該頁面的詳細信息。

6. notion_update_page_properties

   • 更新頁面的屬性。
   • 必需輸入：
     • page_id（字符串）：要更新的頁面的 ID。
     • properties（對象）：要更新的屬性。
   • 返回：關於更新後頁面的信息。

7. notion_create_database

   • 創建新數據庫。
   • 必需輸入：
     • parent（對象）：數據庫的父對象。
     • properties（對象）：數據庫的屬性模式。
   • 可選輸入：
     • title（數組）：數據庫的標題，以富文本數組形式表示。
   • 返回：關於創建的數據庫的信息。

8. notion_query_database

   • 查詢數據庫。
   • 必需輸入：
     • database_id（字符串）：要查詢的數據庫的 ID。
   • 可選輸入：
     • filter（對象）：過濾條件。
     • sorts（數組）：排序條件。
     • start_cursor（字符串）：下一頁結果的遊標。
     • page_size（數字，默認：100，最大：100）：要檢索的結果數。
   • 返回：查詢結果列表。

9. notion_retrieve_database

   • 檢索特定數據庫的信息。
   • 必需輸入：
     • database_id（字符串）：要檢索的數據庫的 ID。
   • 返回：關於該數據庫的詳細信息。

10. notion_update_database

    • 更新數據庫的信息。
    • 必需輸入：
      • database_id（字符串）：要更新的數據庫的 ID。
    • 可選輸入：
      • title（數組）：數據庫的新標題。
      • description（數組）：數據庫的新描述。
      • properties（對象）：更新後的屬性模式。
    • 返回：關於更新後數據庫的信息。

11. notion_create_database_item

    • 在 Notion 數據庫中創建新項。
    • 必需輸入：
      • database_id（字符串）：要添加項的數據庫的 ID。
      • properties（對象）：新項的屬性。這些屬性應與數據庫模式匹配。
    • 返回：關於新創建項的信息。

12. notion_search

    • 按標題搜索頁面或數據庫。
    • 可選輸入：
      • query（字符串）：在頁面或數據庫標題中搜索的文本。
      • filter（對象）：將結果限制為僅頁面或僅數據庫的條件。
      • sort（對象）：對結果進行排序的條件。
      • start_cursor（字符串）：分頁起始遊標。
      • page_size（數字，默認：100，最大：100）：要檢索的結果數。
    • 返回：匹配的頁面或數據庫列表。

13. notion_list_all_users

    • 列出 Notion 工作空間中的所有用戶。
    • 注意：此功能需要升級到 Notion 企業版計劃並使用組織 API 密鑰，以避免權限錯誤。
    • 可選輸入：
      • start_cursor（字符串）：列出用戶的分頁起始遊標。
      • page_size（數字，最大：100）：要檢索的用戶數。
    • 返回：工作空間中所有用戶的分頁列表。

14. notion_retrieve_user

    • 通過用戶 ID 在 Notion 中檢索特定用戶。
    • 注意：此功能需要升級到 Notion 企業版計劃並使用組織 API 密鑰，以避免權限錯誤。
    • 必需輸入：
      • user_id（字符串）：要檢索的用戶的 ID。
    • 返回：關於指定用戶的詳細信息。

15. notion_retrieve_bot_user

    • 檢索與當前令牌關聯的 Notion 機器人用戶。
    • 返回：關於機器人用戶的信息，包括授權集成的人員的詳細信息。

16. notion_create_comment

    • 在 Notion 中創建評論。
    • 要求集成具有 'insert comment' 功能。
    • 要麼指定包含 page_id 的 parent 對象，要麼指定 discussion_id，但不能同時指定兩者。
    • 必需輸入：
      • rich_text（數組）：表示評論內容的富文本對象數組。
    • 可選輸入：
      • parent（對象）：如果使用，必須包含 page_id。
      • discussion_id（字符串）：現有的討論線程 ID。
    • 返回：關於創建的評論的信息。

17. notion_retrieve_comments

    • 從 Notion 頁面或塊中檢索未解決的評論列表。
    • 要求集成具有 'read comment' 功能。
    • 必需輸入：
      • block_id（字符串）：要檢索其評論的塊或頁面的 ID。
    • 可選輸入：
      • start_cursor（字符串）：分頁起始遊標。
      • page_size（數字，最大：100）：要檢索的評論數。
    • 返回：與指定塊或頁面關聯的評論的分頁列表。

📄 許可證

此 MCP 服務器採用 MIT 許可證。這意味著你可以自由使用、修改和分發該軟件，但需遵守 MIT 許可證的條款和條件。有關更多詳細信息，請參閱項目倉庫中的 LICENSE 文件。