Notion MCP サーバー

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統合を作成する:

   • Notion の統合ページにアクセスしてください。

   • 「新しい統合」をクリックします。

   • 統合に名前を付け、適切な権限（「コンテンツの読み取り」、「コンテンツの更新」など）を選択します。

2. 秘密鍵を取得する:

   • 統合から「内部統合トークン」をコピーします。

   • このトークンは認証に使用されます。

3. ワークスペースに統合を追加する:

   • Notion で統合によりアクセスするページまたはデータベースを開きます。

   • 右上の「···」ボタンをクリックします。

   • 「接続」ボタンをクリックし、上記の手順 1 で作成した統合を選択します。

4. Claude Desktop を構成する: claude_desktop_config.jsonに以下を追加します。

または

環境変数

• NOTION_API_TOKEN (必須): Notion API 統合トークン。

• NOTION_MARKDOWN_CONVERSION : 試験的なMarkdown変換を有効にするには、「true」に設定します。これにより、コンテンツ閲覧時のトークン消費量が大幅に削減されますが、ページコンテンツの編集時に問題が発生する可能性があります。

コマンドライン引数

• --enabledTools : 有効にするツールのカンマ区切りリスト（例："notion_retrieve_page,notion_query_database"）。指定すると、リストされたツールのみが利用可能になります。指定しない場合は、すべてのツールが有効になります。

読み取り専用ツールの例 (コピー アンド ペーストしやすい):

詳細設定

マークダウン変換

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

または

NOTION_MARKDOWN_CONVERSIONが"true"に設定されている場合、レスポンスは Markdown 形式に変換されます（ formatパラメータが"markdown"に設定されている場合）。これにより、人間にとってより読みやすくなり、トークンの消費量が大幅に削減されます。ただし、この機能は試験的なため、変換時に元の構造が失われるため、ページコンテンツを編集する際に問題が発生する可能性があります。

ツール呼び出しでformatパラメータを"json"または"markdown"に設定することで、リクエストごとにフォーマットを制御できます。

• コンテンツを表示する場合は、読みやすさを向上させるために"markdown"を使用します

• 返されるコンテンツを変更する必要がある場合は"json"を使用します

トラブルシューティング

権限エラーが発生した場合:

1. 統合に必要な権限があることを確認します。

2. 統合が関連するページまたはデータベースに招待されていることを確認します。

3. claude_desktop_config.jsonでトークンと構成が正しく設定されていることを確認します。

プロジェクト構造

このプロジェクトは、保守性と可読性を向上させるためにモジュール方式で構成されています。

ディレクトリの説明

• 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

• Notion で user_id によって特定のユーザーを取得します。

• 注意: この機能を使用するには、Notion エンタープライズ プランにアップグレードし、権限エラーを回避するために組織 API キーを使用する必要があります。

• 必要な入力:

  • user_id (文字列): 取得するユーザーの ID。

• 返される値: 指定されたユーザーに関する詳細情報。

15. notion_retrieve_bot_user

• Notion 内の現在のトークンに関連付けられているボット ユーザーを取得します。

• 返されるもの: 統合を承認した人物の詳細を含む、ボット ユーザーに関する情報。

16. notion_create_comment

• Notion でコメントを作成します。

• 統合には「コメントの挿入」機能が必要です。

• parentオブジェクトをpage_idまたはdiscussion_idのいずれかで指定します。両方は指定できません。

• 必要な入力:

  • rich_text (配列): コメントの内容を表すリッチ テキスト オブジェクトの配列。

• オプション入力:

  • parent (オブジェクト): 使用する場合は、 page_idを含める必要があります。

  • discussion_id (文字列): 既存のディスカッション スレッド ID。

• 返される値: 作成されたコメントに関する情報。

17. notion_retrieve_comments

• Notion ページまたはブロックから未解決のコメントのリストを取得します。

• 統合には「コメントを読む」機能が必要です。

• 必要な入力:

  • block_id (文字列): コメントを取得するブロックまたはページの ID。

• オプション入力:

  • start_cursor (文字列): ページネーションの開始カーソル。

  • page_size (数値、最大: 100): 取得するコメントの数。

• 戻り値: 指定されたブロックまたはページに関連付けられたコメントのページ区切りリスト。

ライセンス

このMCPサーバーはMITライセンスに基づいてライセンスされています。つまり、MITライセンスの条件に従って、ソフトウェアを自由に使用、改変、配布することができます。詳細については、プロジェクトリポジトリのLICENSEファイルをご覧ください。