MCP Notion Server

🚀 Notion MCP Server

Notion API用のMCPサーバーです。LLMがNotionワークスペースと相互作用できるようにします。さらに、Markdown変換を採用して、LLMとの通信時にコンテキストサイズを削減し、トークンの使用を最適化し、やり取りをより効率的にします。

🚀 クイックスタート

以下の記事で、上記の手順について詳しく説明しています。

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

1. Notion Integrationの作成

• 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: 実験的なMarkdown変換を有効にするには「true」に設定します。これにより、コンテンツを表示する際のトークン消費を大幅に削減できますが、ページコンテンツを編集しようとすると問題が発生する可能性があります。

コマンドライン引数

• --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

🔧 技術詳細

Markdown変換

デフォルトでは、すべてのレスポンスはJSON形式で返されます。実験的なMarkdown変換を有効にして、トークン消費を削減できます。

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

または

{
  "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 Enterpriseプランにアップグレードし、Organization APIキーを使用する必要があります。
    • オプションの入力:
      • start_cursor (文字列): ユーザーをリストするためのページネーションの開始カーソルです。
      • page_size (数値、最大: 100): 取得するユーザーの数です。
    • 返り値: ワークスペース内のすべてのユーザーのページ付きリストです。

14. notion_retrieve_user

    • Notion内でユーザーIDによって特定のユーザーを取得します。
    • 注意: この関数は、権限エラーを回避するために、Notion Enterpriseプランにアップグレードし、Organization APIキーを使用する必要があります。
    • 必要な入力:
      • user_id (文字列): 取得するユーザーのIDです。
    • 返り値: 指定されたユーザーに関する詳細情報です。

15. notion_retrieve_bot_user

    • Notion内で現在のトークンに関連付けられたボットユーザーを取得します。
    • 返り値: ボットユーザーに関する情報で、統合を承認したユーザーの詳細も含まれます。

16. notion_create_comment

    • Notion内にコメントを作成します。
    • 統合に「insert comment」機能が必要です。
    • parentオブジェクトにpage_idを指定するか、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ファイルを参照してください。