Notion MCP完全攻略 — 公式サーバーの6つの落とし穴と2026年新機能
NotionはKanseiLink AEO評価でAAAグレードを獲得するグループウェア系SaaSの代表格だ。公式MCPサーバー（npx @notionhq/notion-mcp-server）は18ツールを提供し、Claude Code・Cursor・VS Codeとのネイティブ統合を実現している。しかしNotion APIとMCPサーバーには、エージェント開発者が必ずハマる独特の仕様が6つある。本記事ではKanseiLink実測データをもとに、AAAグレードの根拠・2つの認証方式の使い分け・6つの落とし穴、そして2026年に追加されたWebhooksとバルク操作APIによる解決策を徹底解説する。
1. なぜNotionはAAAグレードなのか
認証: Integration Token / OAuth 2.0
最終更新: 2026-04-19 (KanseiLink DB)
KanseiLinkがNotionにAAAを付与している根拠は以下の4点だ。
| 評価軸 | Notionの実績 | 評価 |
|---|---|---|
| 公式MCPサーバー | Notion公式（github.com/makenotion/notion-mcp-server）、ホスト型とnpxローカル版の2形式 | ✅ 最高水準 |
| 認証方式 | Integration Token（内部用・シンプル）とOAuth 2.0（公開統合用）の2方式 | ✅ 優秀 |
| API成熟度 | REST API v1（安定版2022-06-28）、カーソルページネーション、バルク操作、Webhook対応 | ✅ 優秀 |
| 2026年の継続投資 | バルク操作API（2026-02-01）・Webhooks（2026-03-01）・APIバージョン2025-09-03追加 | ✅ 積極的 |
一方でtrust_scoreは0.7と中程度に留まる。これはNotionのAPI品質そのものではなく、「接続共有忘れ」「ヘッドレス非対応」など、設定ミスによるエラー発生率が高いことを反映している。後述する6つの落とし穴をあらかじめ把握していれば、スコアは大幅に改善する。
2. 認証方式：2択の使い分け
① Internal Integration Token
最もシンプルな認証方式。ntn_ または secret_ で始まるトークンをNotionヘッダーに設定する。ヘッドレス自動化（cron実行、バックグラウンドエージェント）に対応しており、エージェント開発の第一選択肢。
- 1 notion.so/my-integrations で新しい統合を作成
- 2 「Internal Integration Secret」をコピー（
ntn_またはsecret_で始まる文字列） - 3 リクエストヘッダーに
Authorization: Bearer {token}とNotion-Version: 2022-06-28を設定 - 4 重要：対象ページ/DBのUIで「…（設定）→ コネクト → 統合名を追加」で統合に共有する（この手順を忘れると404エラー）
② OAuth 2.0
複数ユーザーが利用する公開統合に使用する方式。ホスト型MCPサーバーはこのOAuth方式のみ対応しており、ユーザーがブラウザ経由でNotionワークスペースへの権限を付与する必要がある。そのため完全ヘッドレスの自動化には不向き。
- 1 notion.so/my-integrationsで「パブリック統合」を選択して作成
- 2 Token URL:
https://api.notion.com/v1/oauth/token - 3 ユーザーに認可画面を経由してもらうフローが必須
- 4 ホスト型MCPサーバー（Notionサーバー経由）を使う場合はこちらのみ選択可
3. 公式MCPサーバー：ホスト型 vs ローカル版
Notionは2種類のMCPサーバーを提供している。どちらを使うかはユースケースによって決まる。
| 項目 | ホスト型（Notionサーバー経由） | ローカル版（npx） |
|---|---|---|
| 起動方法 | Claude Desktop設定でURL指定 | npx @notionhq/notion-mcp-server |
| 認証 | OAuth 2.0のみ（ユーザー操作必須） | Integration Token または OAuth 2.0 |
| ツール数 | 18ツール（ページレベルのみ） | ブロックレベルツールも一部含む |
| ブロック操作 | ❌ 不可（ページ全体の取得・置換のみ） | ⚠️ 一部可能（ただしソフト非推奨） |
| ヘッドレス実行 | ❌ 不可 | ✅ 可能 |
| 適用場面 | Claude Desktopでの対話的利用 | 自動化・CI/CD・バックグラウンドエージェント |
4. エージェント開発者が必ずハマる6つの落とし穴
Notion APIの最大の罠。Integration Tokenは有効なのに、対象ページ・DBへのAPIアクセスが404を返すケースが頻発する。原因は統合を対象リソースに明示的に「共有」していないこと。Notionのデータ構造は統合が知らないページには一切アクセスできない設計になっている。ページ・DB・ページ内のDBすべてに対してNotionのUI（「…」メニュー → 「コネクト」）から統合を追加する手順が必須。エージェントに統合させる全リソースの事前共有設定が鉄則。
ホスト型NotionMCPは「ページレベル」の操作に限定されている。個別ブロック（段落・見出し・リストアイテム・チェックボックス）の取得・更新・削除・追記は公開されていない。AIミーティングノートのトランスクリプトへのプログラムアクセスもブロックされている。細かいコンテンツ編集が必要な場合は、ローカル版のnpxサーバーかNotion REST APIを直接呼び出すこと（ただしローカル版のブロックツールはNotionによりソフト非推奨扱い）。
ホスト型MCPサーバーはOAuth 2.0認証のみ対応しており、ユーザーが都度ブラウザで認可するフローが前提となっている。cronジョブ・GitHub Actions・バックグラウンドエージェントなど人間が介在しない自動化には使えない。完全ヘッドレスが必要な場合はIntegration Tokenを使うローカル版npxサーバーが唯一の選択肢。
Notionのデータベースプロパティはすべて深いネスト構造を持つ。properties.Name.title[0].text.content のようにアクセスする必要があり、単純な record.Name では取得できない。タイプ（title / rich_text / number / select / date）によってアクセスパスが異なる点も注意。エージェントにNotionデータを扱わせる前に、プロパティスキーマの事前取得（DBスキーマキャッシュ）を実装することを強く推奨する。
// Notion DB query レスポンス例
{
"results": [{
"id": "page_abc123",
"properties": {
"Name": {
"type": "title",
"title": [{ "text": { "content": "プロジェクトA" } }]
},
"Status": {
"type": "select",
"select": { "name": "進行中", "color": "blue" }
},
"Due": {
"type": "date",
"date": { "start": "2026-05-01" }
}
}
}]
}
// ✅ 正しいアクセスパス
const name = page.properties.Name.title[0]?.text.content;
const status = page.properties.Status.select?.name;
const due = page.properties.Due.date?.start;
// ❌ 間違い: page.properties.Name → オブジェクト全体が返る
Notion APIの異例な仕様のひとつ。データベースのレコード一覧取得は GET /v1/databases/{id} ではなく、フィルター条件をBodyに持つ POST /v1/databases/{id}/query を使う。APIドキュメントを斜め読みしてGETでクエリしようとするとエラーになる。また新APIバージョン（2025-09-03）では query-data-source というツール名に変更されているため、MCPバージョンに応じた名前を確認すること。
Notionはファイルアップロードと添付ファイルアクセスをMCPサーバー経由で提供していない（REST API・ホスト型ともに未対応）。また、コメント一覧の取得は可能だが、特定のコメントIDによる個別取得はサポートされていない。ファイル処理が必要なワークフローでは代替手段（S3・Google Driveとの連携、コメント一覧からのフィルタリング）を検討すること。
5. 2026年の新機能：2つのゲームチェンジャー
Webhooks（POST /v1/webhooks）の追加により、ポーリングが不要になった。ページ更新・DB変更・コメント追加などのイベントをNotionがプッシュ通知してくれるため、エージェントが変更検知のためにAPIを定期呼び出しする必要がなくなった。Webhookはレート制限（3 req/s）に計上されない点が大きなメリット。変更監視ユースケースではポーリングをWebhookに切り替えることを強く推奨する。
バルク操作エンドポイント（POST /v1/bulk/pages）の追加により、大量データの書き込み効率が劇的に改善した。1リクエストで最大100ページを処理でき、従来100個のPATCHリクエストが必要だったケースを1リクエストで完結できる。レート制限（180 req/min）に対して最大100倍の処理効率を実現。バッチ処理やデータ移行ワークフローで積極的に活用すべきAPI。
6. 実装チェックリスト
Notion MCPをエージェントに組み込む前に以下の手順を確認する。
① 統合の共有設定：エージェントがアクセスするすべてのページ・DBをNotionのUIから統合に共有済みか確認
② Notion-Versionヘッダー：2022-06-28（安定版）または 2025-09-03（新Data Sourcesモデル）を明示的に設定
③ DBスキーマキャッシュ：クエリ前に一度スキーマを取得してプロパティ名・タイプをキャッシュ
④ カーソルページネーション：has_more と next_cursor を使って全件取得（page_size最大100）
⑤ Rate Limit対応：HTTP 429受信時にRetry-Afterを読んで待機、バルク操作を優先使用
⑥ 変更監視はWebhookで：ポーリング不要、レート制限節約
// POST /v1/databases/{id}/query — フィルター + ページネーション
async function queryAllPages(dbId, token) {
const pages = [];
let cursor = null;
do {
const body = {
filter: { property: "Status", select: { equals: "Done" } },
page_size: 100,
...(cursor && { start_cursor: cursor })
};
const res = await fetch(`https://api.notion.com/v1/databases/${dbId}/query`, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Notion-Version": "2022-06-28",
"Content-Type": "application/json"
},
body: JSON.stringify(body)
});
const data = await res.json();
pages.push(...data.results);
cursor = data.has_more ? data.next_cursor : null;
} while (cursor);
return pages;
}
まとめ：Notion MCPはAAAグレードだが、設定が命
NotionのAAAグレードは正当だ。公式MCPサーバー、2種類の認証、成熟したREST API、そして2026年に追加されたWebhooks・バルク操作APIは、エージェント開発者にとって強力な武器となる。
ただし「接続共有忘れ」問題に代表されるように、設定ミスによるエラーが多いサービスでもある。本記事で解説した6つの落とし穴と実装チェックリストを事前に把握することで、立ち上げ時間を大幅に短縮できる。
特に注目すべきは2026年の新機能だ。Webhooks（レート制限不要の変更検知）とバルク操作API（最大100倍の書き込み効率）は、Notionを使ったエージェントワークフローの設計を根本から変える可能性を持っている。