Notion MCP Server

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ファイルをご覧ください。