Notion ReadOnly MCP Server

Notion ReadOnly MCP サーバー

このプロジェクトは、Notion API 用に最適化された読み取り専用 MCP サーバーを実装しています。AI アシスタントが Notion のコンテンツを照会、取得する際のパフォーマンスと効率に重点を置いています。

主な改善点

• 読み取り専用設計：データ取得操作に特化し、Notion のコンテンツへの安全なアクセスを確保しています。
• ツールセットの最小化：公開する Notion API ツールの数を 15 個以上から、ドキュメント分析に不可欠な 6 個に削減しました。
• 並列処理：ブロックコンテンツの取得に非同期および並列の API リクエストを導入してパフォーマンスを向上させ、応答時間を大幅に短縮しました。
• データベースアクセスの拡張：データベース、ページプロパティ、コメントの取得操作に対応しました。
• AI アシスタント向けの最適化：ツール数を大幅に減らすことで、Cursor などの AI アシスタントで「ツールが多すぎるとパフォーマンスが低下する」という問題に対処しています。これにより、モデルのツール数を約 40 個に制限できます。

ツールの比較

この読み取り専用実装では、標準の Notion API 統合と比べて公開するツールを大幅に減らし、AI アシスタントのパフォーマンスと互換性を向上させています。

ツールセットを減らすことで、必要な機能をすべて提供しながら、AI アシスタントのパフォーマンスを最適化するために推奨されるツール数の上限内に収めやすくなります。

インストール

1. Notion でインテグレーションを設定する：

https://www.notion.so/profile/integrations にアクセスし、新しい内部インテグレーションを作成するか、既存のものを選択します。

公開する Notion API の範囲を読み取り専用操作に限定していますが、LLM にアクセスを許可することでワークスペースのデータが危険にさらされるリスクはゼロではありません。セキュリティを重視するユーザーは、インテグレーションの Capabilities をさらに設定することをおすすめします。

たとえば、「Configuration」タブで「Read content」のみを許可し、読み取り専用のインテグレーショントークンを作成できます。

2. クライアントに MCP 設定を追加する：

npm を使用する場合：

以下を .cursor/mcp.json または claude_desktop_config.json に追加します（MacOS の場合：~/Library/Application\ Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "notion-readonly-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Docker を使用する場合：

以下を .cursor/mcp.json または claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "taewoong1378/notion-readonly-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

ntn_**** をインテグレーションシークレットに置き換えてください。インテグレーションの設定タブで確認できます。

3. コンテンツをインテグレーションに接続する：

関連するページとデータベースがインテグレーションに接続されていることを確認します。

ページを開き、3 点メニューをクリックして「Connect to integration」を選択します。

利用可能なツール

この最適化されたサーバーは、不可欠な読み取り専用の Notion API ツールのみを公開します。

• API-retrieve-a-page：ページ情報を取得します
• API-get-block-children：ページのコンテンツブロックを取得します（並列処理に対応）
• API-retrieve-a-block：特定のブロックの詳細を取得します
• API-retrieve-a-database：データベース情報を取得します
• API-retrieve-a-comment：ページまたはブロックのコメントを取得します
• API-retrieve-a-page-property：ページの特定のプロパティ情報を取得します
• API-get-one-pager：新機能！ Notion ページ全体と、そのすべてのブロック、データベース、関連コンテンツを再帰的に取得します

標準実装の 15 個以上に対して、不可欠な 7 つのツールに絞ることで、次のことを実現します。

1. Cursor や Claude など、ツール数に制限のある AI アシスタントでのパフォーマンスが向上します
2. AI モデルが適切なツールを選ぶ際の認知負荷が軽減されます
3. 検討が必要な API の選択肢が少なくなり、応答時間が短縮されます
4. API の公開範囲を最小限にすることで、セキュリティが強化されます

コンテンツの自動探索

新しい API-get-one-pager ツールを使うと、複数回の API 呼び出しを必要とせず、Notion ページを強力に探索できます。

• 再帰的な取得：ネストされたブロックを含むページ構造全体を自動的にたどります
• 並列処理：パフォーマンスを最大限に高めるため、複数のブロックとその子要素を同時に取得します
• インテリジェントなキャッシュ：取得したデータを保存し、API の重複呼び出しを最小限に抑えます
• 包括的なコンテンツ：ページ、ブロック、データベース、コメント、詳細なプロパティ情報を含みます
• カスタマイズ可能な深度：詳細さとパフォーマンスのバランスを取りながら、再帰の深度を調整できます

One Pager ツールの使用

{
  "page_id": "YOUR_PAGE_ID",
  "maxDepth": 5,               // Optional: Maximum recursion depth (default: 5)
  "includeDatabases": true,    // Optional: Include linked databases (default: true)
  "includeComments": true,     // Optional: Include comments (default: true)
  "includeProperties": true    // Optional: Include detailed page properties (default: true)
}

この自動探索機能は、Notion ページ全体を把握するために多数の個別の API 呼び出しが必要となる AI アシスタントにとって特に便利で、応答を大幅に高速化し、効率を高めます。

非同期処理

このサーバーでは、大規模な Notion ドキュメントを処理するために、高度な並列処理技術を実装しています。

• 複数のリクエストをまとめて、並行して処理します
• ブロックの子要素のページネーションを自動的に処理します
• 結果を効率的に集約してから返します
• コンソールログによって、応答形式に影響を与えずに処理状況を確認できます

使用例

1. 次の指示を使用します。

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

AI は、ブロックコンテンツを並列処理しながら、ページの詳細を効率的に取得します。

2. データベース情報を使用します。

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

開発

ビルド：

pnpm build

実行：

pnpm dev

ライセンス

MIT

AI アシスタントのパフォーマンス上の利点

Cursor や Claude などの最新の AI アシスタントには、効果的に処理できるツール数に制限があります。

• 多くのモデルは、合計 40 個を超えるツールに対応できない場合があります
• ツールが多すぎると、全体的なパフォーマンスや推論能力が低下する可能性があります
• 複雑なツールセットは、応答の遅延や意思決定の難しさにつながります

この読み取り専用の実装では、不可欠な機能をすべて維持しながら、Notion API の公開範囲を意図的に縮小し、こうした制限に対処しています。その結果、次のことが実現します。

• AI アシスタントの応答がより速く、信頼性が高くなります
• Notion コンテンツを操作する際の精度が向上します
• API 設計を必要な範囲に絞ることで、全体的なパフォーマンスが向上します