notion-full-mcp

Name: notion-full-mcp
Author: cphoskins

ローカル

github.com/cphoskins生産性03 日前に更新

リポジトリ

notion-full-mcp について

notion-full-mcpは、MCPクライアント向けにページの読み取り、編集、復元を行うNotionサーバーです。テーブルやファイルも扱い、ツールの読み取り専用・追加・破壊的な操作を注釈で示します。

主な機能

01ページ内容の再帰的な読み取り
02ブロックとテーブルセルの編集
03スナップショットとロールバック復元
04Notionファイルのアップロードとダウンロード
05ページの移動・コピー・復元

活用シーン

01ページとネストした内容の確認
02ページのテキストやテーブル行の変更
03ページ内容のバックアップと復元
04Notionページへのファイル挿入

MCP 対応

Notionのページ、ブロック、データベース、コメント、ユーザー、ファイルを操作する33種類のツールをMCPクライアントに公開します。ツールの注釈で読み取り専用、追加、破壊的な操作を区別できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "cphoskins-notion-full": {
      "command": "uvx",
      "args": [
        "notion-full-mcp"
      ],
      "env": {
        "NOTION_API_TOKEN": "<NOTION_API_TOKEN>",
        "NOTION_MCP_FILE_ROOT": "<NOTION_MCP_FILE_ROOT>"
      }
    }
  }
}

起動コマンドuvx notion-full-mcp

設定が必要な環境変数

NOTION_API_TOKENシークレットYour Notion integration API token (starts with ntn_)

NOTION_MCP_FILE_ROOTOptional directory that uploads, downloads and snapshots are confined to

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypinotion-full-mcp0.5.1stdio

ツール

掲載時のツール一覧 · 2 日前に更新

パラメーター	型	必須	説明
query	string	はい
max_results	integer	いいえ

詳細

notion-full-mcp

Notion MCP サーバーです。ページの詳細な読み取り、ブロックのピンポイント編集、安全なスナップショット／復元、ファイルのアップロード（Notion ホストの画像と PDF）、テーブル行の操作、ページの移動とコピー、ゴミ箱からのページ復元に対応しています。

v0.5.1 の新機能

ツールの注釈。 各ツールは読み取り専用、追加、破壊的のいずれかを宣言するため、MCP クライアントは確認を求めずに実行するツールを判断できます。
MCP レジストリ。 サーバーが公式 MCP レジストリに io.github.cphoskins/notion-full-mcp として公開されました。

v0.5.0 の新機能

復元後もページ内の順序を保持します。 ページに残っているサブページ、インラインデータベース、Notion ホストのファイルには手を加えず、スナップショットの順序に沿って復元したコンテンツを書き込みます。
ゴミ箱から項目を復元します。 スナップショットの作成後に削除されたサブページ、データベース、ホストされたファイルは、ID、コメント、履歴を保持したまま Notion のゴミ箱から復元されます。
スナップショットにファイルを含められます。 include_files を指定して snapshot_page を実行すると、Notion ホストの画像やファイルが JSON ファイルと同じ場所にダウンロードされ、復元時に元の場所へ再アップロードされます。
修正：ブロックの後に 100 個を超えるブロックを挿入する場合も、正しい順序が保たれるようになりました。

v0.4.0 の新機能

復元でコンテンツが失われることはなくなりました。 restore_page_from_snapshot はスナップショットを先に書き込み、成功した後でのみ古いブロックを削除します。復元に失敗するとロールバックされ、ページは元の状態のままです。サブページ、インラインデータベース、Notion ホストのファイルは削除されません。
move_page が動作するようになりました。 Notion の移動エンドポイントを使用するため、ページの ID、コンテンツ、コメント、サブページが保持されます。
copy_page_to_parent はコピーできなかった内容を報告します。 コピーできないブロックタイプは skipped に列挙され、すべてコピーできた場合にのみ元のページがアーカイブされます。
大規模で階層の深いコンテンツに対応しました。 2 階層を超えるネストされたリスト、100 行を超えるテーブル、2,000 文字を超えるテキストは、自動的に複数のリクエストに分割されます。
編集後もメンションと数式が保持されます。 検索／置換、復元、コピーでは、ユーザー、ページ、データベース、日付へのメンションとインライン数式が保持されます。
エラー処理とレート制限への対応を改善しました。 エラーには Notion 独自のコードとメッセージが含まれます。レート制限されたリクエストは Retry-After に従って再試行されます。
データベース行にタイトルが表示されます。 検索、ページ情報の取得、作成では、タイトル列の名前にかかわらずタイトルが返されます。
対応するブロックタイプが増えました。 数式、ブックマーク、埋め込み、外部ホストのメディアブロックが、スナップショット／復元やコピーで保持されます。
ファイルの操作範囲を制限できます。 NOTION_MCP_FILE_ROOT を設定すると、アップロード、ダウンロード、スナップショットの保存先を 1 つのディレクトリに限定できます。

v0.3.0 の新機能

ゴミ箱からページを復元できます。 restore_page は archived=False を送信して、ページのアーカイブを明示的に解除します。これはページ上の delete_block に相当し、archived=False をブロックする update_page の意図的な安全ガードを回避できます。親ページを復元すると、連鎖してアーカイブされた子ページも自動的に復元されます。
親ページをまたぐ破壊的なページコピーに対応しました。 copy_page_to_parent は、Notion の公開 API が親ページの変更をサポートしていないことへの回避策です。タイトル、アイコン、コンテンツを保持して対象の親ページにページを再作成し、元のページをアーカイブします。段落、見出し、リスト、テーブル、区切り線、コードブロック、画像／ファイルブロックに対応しています。ソースにネストされた child_page の子孫がある場合は実行を拒否します（それらは手動でコピーしてください）。
move_page は動作するふりをしなくなりました。 Notion の PATCH /pages/{id} エンドポイントは親ページの変更を暗黙に無視するため、ツールは代わりにエラーを返すようになりました。（v0.4.0 で実際の移動が実装されました。）

v0.2.0 の新機能

Notion へのファイルアップロード。 外部の画像ホストに頼らず、画像やファイルを Notion 独自のワークスペースストレージに直接アップロードできます。PNG、JPEG、SVG、GIF、PDF、その他 Notion がサポートするすべての添付ファイル形式に対応しています。
画像ブロック用ヘルパー。 upload_image_as_block はファイルをアップロードし、1 回の呼び出しで指定位置に挿入します。replace_image_block は親ブロック内の位置を維持したまま、既存の画像の内容を差し替えます。download_image_block は任意の画像ブロックのファイルをディスクにダウンロードします。
テーブル行の操作。 insert_table_row は幅を自動で検証しながら、既存のテーブルに行を追加します。update_table_cell は単一セルのテキストを置き換えます。小さな編集のためにテーブル全体を作り直す必要はありません。

インストール

pip install notion-full-mcp
# or
uv pip install notion-full-mcp

クイックスタート

export NOTION_API_TOKEN="your-token-here"
notion-mcp

Claude Code との連携

~/.claude.json の mcpServers の下に追加します。

{
  "notion-full": {
    "type": "stdio",
    "command": "uvx",
    "args": ["notion-full-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

または、ローカル開発の場合：

{
  "notion-full": {
    "type": "stdio",
    "command": "uv",
    "args": ["run", "--directory", "/path/to/notion-full-mcp", "notion-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

ツール（33）

検索とページ

ツール	説明
`search_pages`	タイトルでページを検索します
`search`	ページやデータベースを検索します
`get_page_info`	ページのメタデータ（タイトル、親、日付、URL）を取得します
`create_page`	親ページまたはデータベースの下に新しいページを作成します
`update_page`	ページのタイトル、アイコン、またはアーカイブ状態を更新します
`move_page`	ID と内容を維持したまま、ページを新しい親ページの下に移動します
`restore_page`	ゴミ箱からページ（および連鎖的にアーカイブされた子ページ）を復元します
`copy_page_to_parent`	新しい親ページまたはデータベースの下にページを再作成します。すべてのブロックがコピーされた場合にのみ、元のページをアーカイブします

読み取り

ツール	説明
`read_page_deep`	ページと、ネストされたすべての子要素を再帰的に読み取ります
`list_block_children`	ブロックまたはページの直接の子要素を一覧表示します
`get_block`	ID を指定して単一のブロックを取得します

編集

ツール	説明
`update_block_text`	ブロック内のすべてのテキストを置き換えます
`find_replace_in_block`	書式を維持したままテキストを検索・置換します
`update_block_rich_text`	リッチテキストの詳細な指定を使って更新します

挿入

ツール	説明
`insert_text_after`	指定したブロックの後にテキストブロックを挿入します（paragraph、heading_1/2/3、bulleted_list_item、numbered_list_item、quote、callout、toggle、to_do、code、divider）
`insert_blocks_after`	指定したブロックの後に複数のブロックを挿入します
`append_blocks_to_page`	ページの末尾にブロックを追加します

削除

ツール	説明
`delete_block`	ID を指定してブロックを削除します

ツール	説明
`create_comment`	ページにコメントを追加します
`list_comments`	ページまたはブロックのすべてのコメントを一覧表示します

データベース

ツール	説明
`get_database`	データベースのメタデータとスキーマを取得します
`query_database`	フィルターと並べ替えを指定してデータベースをクエリします

ユーザー

ツール	説明
`get_self`	現在認証されているユーザーまたはボットを取得します
`list_users`	ワークスペースのすべてのユーザーを一覧表示します

スナップショット／復元

ツール	説明
`snapshot_page`	ページ構造全体を JSON として保存します。`include_files` を指定すると、Notion にホストされている画像やファイルも保存します
`restore_page_from_snapshot`	スナップショットからページの内容を復元します。最初に書き込みを行い、失敗時にはロールバックします。サブページとデータベースはそのまま保持し、削除されたものはゴミ箱から復元して、保存済みファイルを再アップロードします

メディアとファイル

ツール	説明
`upload_file`	ファイルをNotion独自のワークスペースストレージにアップロードします（`file_upload_id`を返します）
`upload_image_as_block`	画像をアップロードし、新しい画像ブロックとして1ステップで挿入します（ブロックの後、またはページの末尾に追加）
`replace_image_block`	既存の画像ブロックを新しくアップロードしたファイルに置き換え、位置を維持します
`download_image_block`	画像ブロックの画像ファイルをディスクにダウンロードします。外部URL、Notionホストのファイル、`file_upload`参照に対応します
`upload_file_as_block`	任意のファイル（PDF、添付ファイル）をアップロードし、ファイルブロックとして挿入します

テーブル

ツール	説明
`insert_table_row`	幅を自動検証して、既存のテーブルに新しい行を挿入します
`update_table_cell`	テーブル行の単一セルのテキストを置き換えます

ツールのアノテーション

各ツールにはMCPアノテーションが付与されているため、クライアントは確認を求めずに実行しても安全かどうかを判断できます。

読み取り専用（11）： 検索、ページとブロックの読み取り、コメント一覧、データベースの読み取り、ユーザー検索。
損失なく追加（13）： 挿入、末尾への追加、アップロード、ページとコメントの作成、move_page、restore_page、およびローカルファイルを書き込む2つのツール（snapshot_page、download_image_block）。
破壊的操作としてマーク済み（9）： update_block_text、update_block_rich_text、find_replace_in_block、update_table_cell、replace_image_block、delete_block、update_page、copy_page_to_parent、restore_page_from_snapshot。既存のコンテンツを上書き、削除、またはアーカイブします。

ブロックのサポートと制限

往復（スナップショット／復元とコピー）： 段落、見出し（トグル可能なものを含む）、箇条書きと番号付きリスト、ToDo、引用、コールアウト、トグル、コード、区切り線、テーブル、カラム、目次、数式、ブックマーク、埋め込み、外部ホストの画像、ファイル、動画、PDF、音声ブロック。
一から再作成されないもの： サブページ、インラインデータベース、同期ブロック。コピー時にはskippedとして報告されます。
これらのブロックとNotionホストのファイルの復元：
- ページに残っている場合： そのまま保持され、スナップショットの順序に従って復元されたコンテンツがその周囲に書き込まれます（preserved）。スナップショットの順序からドラッグして移動したブロックは、その位置に残ります（out_of_order）。
- ファイルがスナップショットとともに保存されている場合： 再アップロードされ、元の位置に再作成されます（uploaded）。20 MBを超えるファイル、またはワークスペースのアップロード上限を超えるファイルはアップロードされません。
- Notionのゴミ箱にある場合： 同じブロックとして復元されます（restored_from_trash）。Notionはブロックをページの末尾に戻すため、ページに残っていてスナップショットで後にあったブロックは、その上に配置され、out_of_orderとして報告されます。
- ゴミ箱からも消えており、保存済みファイルもない場合： 復元できません（skipped）。
- out_of_orderブロックを移動しない理由（設計上の仕様）： Notion APIにはブロックを再配置する方法がありません。サブページまたはデータベースを移動する唯一の方法は、ゴミ箱に移してから復元することです。この方法ではページの末尾に移動し、途中で失敗した場合はゴミ箱に残ってしまいます。復元処理では再作成できないものを削除しないため、ブロックを報告し、適切な位置にドラッグしていただくようにしています。
スナップショット： サブページとインラインデータベースは、それ自体のコンテンツを含めず、ブロックとして記録します。Notionホストのファイルは、include_filesを指定した場合にのみ保存されます。指定しない場合、スナップショットには1時間以内に期限切れとなるリンクが保存されます。
クエリ： query_databaseは最大500行を返し、該当する行がそれより多い場合はtruncatedを設定します。
検索／置換： 1つの書式設定範囲内で一致を検索します。太字やリンクの境界をまたぐ語句は、見つからなかったものとして報告されます。
APIバージョン： リクエストではNotion APIバージョン2022-06-28を使用します。

設定

変数	必須	用途
`NOTION_API_TOKEN`	はい	インテグレーションシークレット
`NOTION_MCP_FILE_ROOT`	いいえ	設定すると、アップロード、ダウンロード、スナップショットファイルはこのディレクトリ内にある必要があります

開発

uv run pytest --cov=notion_mcp      # unit tests, no credentials needed

ライブチェックでは、実際のワークスペースで各ツールを実行します。指定した親ページの下にスクラッチページを1つ作成し、完了後にゴミ箱へ移動します。

export NOTION_API_TOKEN="your-token-here"
export NOTION_TEST_PARENT_PAGE="page-id-shared-with-the-integration"
uv run python scripts/live_check.py

Notion API トークン

https://www.notion.so/my-integrations にアクセスします
新しいインテグレーションを作成します
トークンをコピーします（ntn_で始まります）
アクセスするページやデータベースをインテグレーションと共有します

ライセンス

MIT

Markdown 対応

ログインしてコメント

基本情報

作者: cphoskins
言語: python
バージョン: 0.5.1
トランスポート: stdio
掲載日: 2026年11月11日
最終更新: 3 日前
公式 Registry: io.github.cphoskins/notion-full-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

notion-full-mcp

notion-full-mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

notion-full-mcp

v0.5.1 の新機能

v0.5.0 の新機能

v0.4.0 の新機能

v0.3.0 の新機能

v0.2.0 の新機能

インストール

クイックスタート

Claude Code との連携

ツール（33）

検索とページ

読み取り

編集

挿入

削除

コメント

データベース

ユーザー

スナップショット／復元

メディアとファイル

テーブル

ツールのアノテーション

ブロックのサポートと制限

設定

開発

Notion API トークン

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？