Easy Notion Mcp

npx easy-notion-mcp

目次： 比較 · セットアップ · CLI プロファイル · 設定 · Markdown を使う理由 · 仕組み · ツール · MCP リソース · ブロックの種類 · 往復変換 · データベース · クックブック · セキュリティ · 安定性 · FAQ · コミュニティ

easy-notion-mcp は他の Notion MCP サーバーと比べてどう違いますか？

easy-notion-mcp はどれくらいトークンを節約できますか？

ページのコンテンツを読み取る際のレスポンストークン数は、公式の Notion MCP サーバーと比べて約 6～7分の1 です。Notion の生のブロック JSON には、コンテンツを読むエージェントが必要としないブロックごとのメタデータ（ブロック ID、タイムスタンプ、作成者オブジェクト）が含まれているためです。一般的には約5～7分の1で、コードが多いページでは約3分の1、リッチなページでは約15分の1となり、ページのコンテンツの94％以上が保持されます。公式の生 JSON サーバーと比較した測定値であり、他の Markdown ベースのサーバーとはおおむね同等です。

節約できるのはメタデータの省略によるもので、エンコーディングの効率性によるものではありません。同じ情報量であれば、2つの形式のコストはほぼ同じです（共通の中間表現の比率は、完全に表現されたページ形式で約1.0～1.06倍、一般的な文章で1.32倍です）。したがって、節約分は、生の JSON に含まれるもののコンテンツの読み取りでは使われない、ブロックごとのメタデータ（ブロック UUID、タイムスタンプ、作成者オブジェクト、注釈ラッパー）です。データベースクエリでも、コンテンツをすべて保持した場合に同様に約7分の1になります。

方法論、クラスごとの結果、すべての注意事項については、.meta/research/token-bench-results-2026-06-13.md を参照してください（scripts/bench/lib/recompute-tiers.ts で再実行できます）。

easy-notion-mcp はどのようにセットアップしますか？

API トークンを使う場合

Notion インテグレーションを作成し、トークンをコピーして、ページを共有してください。

Claude Code：

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_your_integration_token \
  -- npx -y easy-notion-mcp

これにより、サーバーが Claude Code のユーザーレベル設定（-s user）に登録され、-e を介して NOTION_TOKEN が MCP の子プロセスに直接渡されます。シェル環境や rc ファイルは変更されません。トークンは Claude Code の設定ファイル内に保存され、このサーバーに限定されるため、他のプロセスからは見えません。create_page のデフォルトの親ページを設定するには、同じコマンドに -e NOTION_ROOT_PAGE_ID=<page-id> を追加してください。

OpenClaw：

openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'

その後、OpenClaw を起動する前に、親シェル環境を通じてトークンを設定してください。

export NOTION_TOKEN=ntn_your_integration_token

この export 形式は、親シェル環境を継承するあらゆる MCP クライアントで使える汎用的な代替手段です。ただし、シェルの rc ファイルに追加しない限り、現在のシェルセッションでのみ有効です。rc ファイルへの追加には独自のセキュリティ上の影響があるため、特に Claude Code では、上記の -e 形式を優先してください。

Claude Desktop / Cursor / Windsurf — MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

設定ファイルの場所：Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json

{
  "servers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

コンテキスト使用量を抑えた Notion アクセス向けの CLI プロファイル

エージェントに MCP ツール一式を読み込ませずに Notion へのアクセスを提供したい場合や、権限モード別に Notion インテグレーションを使い分けたい場合は、easy-notion CLI を使用します。プロファイルはデフォルトで ~/.config/easy-notion-mcp/profiles.json に保存され、生のトークンではなく環境変数名を参照します。

export NOTION_WORK_READONLY=ntn_readonly_token
export NOTION_WORK_WRITE=ntn_readwrite_token

npx -y --package easy-notion-mcp easy-notion profile add work-ro \
  --token-env NOTION_WORK_READONLY \
  --mode readonly \
  --default

npx -y --package easy-notion-mcp easy-notion profile add work-rw \
  --token-env NOTION_WORK_WRITE \
  --mode readwrite \
  --root-page-id your_root_page_id

読み取りコマンドは読み取り専用プロファイルで実行できます。

npx -y --package easy-notion-mcp easy-notion --profile work-ro search "roadmap" --filter pages
npx -y --package easy-notion-mcp easy-notion --profile work-ro page read PAGE_ID --include-metadata
npx -y --package easy-notion-mcp easy-notion --profile work-ro content search-in-page PAGE_ID --query "launch" --within-toggle "Script"

変更を伴うコマンドには、読み書き可能なプロファイルが必要です。

npx -y --package easy-notion-mcp easy-notion --profile work-rw content append PAGE_ID --markdown "## Update"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content update-toggle PAGE_ID --title "Script" --markdown-file ./script.md
npx -y --package easy-notion-mcp easy-notion --profile work-rw content archive-toggle PAGE_ID --title "Done"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content restore-toggle ARCHIVED_BLOCK_ID

破壊的な CLI コマンドは、読み取り専用の事前確認として --dry-run をサポートしています。可能な場合は、同じ検索と Markdown の検証を実行し、would_delete_block_ids、would_update、would_archive、would_restore などの予定フィールドを返します。Notion には変更を加えません。

エージェントのルーティング向けの軽量スキルは、このリポジトリの skills/easy-notion-cli/ で公開されています。複数の MCP サーバーを登録する代わりに、プロファイルベースで Notion にアクセスする際は CLI を優先するよう、エージェントに指示します。

OAuth を使用する場合

API トークン＋stdio は、手軽さを重視したデフォルトの方法です。共有環境で実行する場合や、ユーザーごとにアクセスを管理したい場合は、OAuth を使うとトークンをコピー＆ペーストせずに認証できます。

サーバーを起動します：

npx -p easy-notion-mcp easy-notion-mcp-http

NOTION_OAUTH_CLIENT_ID と NOTION_OAUTH_CLIENT_SECRET の環境変数が必要です。以下のOAuth のセットアップを参照してください。

Claude Code：

claude mcp add notion --transport http http://localhost:3333/mcp

OpenClaw：

openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"

Claude Desktop：

「Settings」→「Connectors」→「Add custom connector」の順に開き、http://localhost:3333/mcp を入力します。

ブラウザーで Notion の認証ページが開きます。共有するページを選択して「Allow」をクリックすれば完了です。

{
  "mcpServers": {
    "easy-notion-mcp": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token",
        "NOTION_ROOT_PAGE_ID": "your_root_page_id"
      }
    }
  }
}

Dify / n8n / FlowiseAI（Docker ベースのプラットフォーム）：

ホストマシンで HTTP サーバーを実行します。

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token \
  NOTION_MCP_BIND_HOST=0.0.0.0 \
  NOTION_MCP_BEARER=$NOTION_MCP_BEARER \
  npx -p easy-notion-mcp easy-notion-mcp-http

プラットフォームの MCP サーバー設定で、localhost の代わりに host.docker.internal を使い、リクエストヘッダーにベアラーを追加します。

http://host.docker.internal:3333/mcp
Authorization: Bearer <your NOTION_MCP_BEARER value>

localhost を使わない理由： これらのプラットフォームは通常、Docker 上で実行されます。コンテナー内の localhost はホストマシンではなく、コンテナー自体を指します。host.docker.internal を使うと、この隔たりを解消できます。

HTTP のホストとベアラー： HTTP サーバーはデフォルトで 127.0.0.1 にバインドされ、静的トークンモードでは NOTION_MCP_BEARER が必要です。host.docker.internal はホストのブリッジ IP に接続するため、ホストで NOTION_MCP_BIND_HOST=0.0.0.0 を設定し、すべてのクライアントリクエストにベアラーヘッダーを送信してください。ユーザーごとにベアラーを発行する OAuth モードは、Docker の共有環境における代替手段です。

easy-notion-mcp は、MCP 対応のあらゆるクライアントで動作します。サーバーは stdio（API トークンモード）または HTTP（OAuth または API トークンモード）で実行されます。

セットアップ中に不明点があれば、Discord コミュニティで質問できます。#easy-notion-mcp チャンネルでは、セットアップや設計に関する議論を扱っています。バグはGitHub のイシューに報告してください。

設定

Stdio モード（API トークン）

.env ファイルについて（コントリビューター向け）： easy-notion-mcp は dotenv を使い、現在の作業ディレクトリから .env ファイルを読み込みます。実際には、リポジトリをクローンしたチェックアウトからサーバーを実行する場合（npm install && npm run build の後に node dist/index.js を実行する場合）に限り、.env がそのまま機能します。これは、リポジトリのルートがカレントディレクトリになるためです。任意のディレクトリから npx easy-notion-mcp 経由でパッケージを実行する場合や、グローバルインストールした場合は、.env は読み込まれません。これは標準的な npm CLI の動作です。npx を使う場合は、上記のClaude Code のセットアップで -e フラグを使って NOTION_TOKEN を渡すか、MCP クライアントの設定の env ブロックで指定してください。

OAuth / HTTP トランスポート

npx -p easy-notion-mcp easy-notion-mcp-http を実行すると、OAuth 対応の HTTP サーバーが起動します。

OAuth 認証情報を取得するには、notion.so/profile/integrations で公開インテグレーションを作成し、リダイレクト URI として http://localhost:3333/callback を設定します。

OAuth モードでは、NOTION_ROOT_PAGE_ID がなくても create_page を利用できます。ページはデフォルトでユーザーのプライベートワークスペースのセクションに作成されます。

HTTP モードのセキュリティ方針

HTTP トランスポートは、ベアラーシークレットを使用した単一オペレーターによるセルフホスト、または共有デプロイ向けの OAuth など、信頼できるネットワークでの利用を想定して設計されています。オープンインターネットに直接公開するための堅牢化はされていません。リモートアクセスが必要な場合は、前段に TLS 対応のリバースプロキシを配置してください。

静的トークンモードではベアラーが必須です。 NOTION_TOKEN だけを設定して npx -p easy-notion-mcp easy-notion-mcp-http を起動すると、起動は拒否されます。サーバーの環境変数に共有シークレットのベアラーを設定し、すべての /mcp リクエストで Authorization: Bearer <secret> として送信するよう MCP クライアントを設定してください。

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx -p easy-notion-mcp easy-notion-mcp-http

ベアラーは crypto.timingSafeEqual で比較されます。ベアラーがない場合、または誤っている場合は、401 { "error": "invalid_token" } が返されます。シークレットをローテーションするには、新しい値でサーバーを再起動してください。

デフォルトのバインド先はループバックです。 デフォルトでは、サーバーは 127.0.0.1 にバインドし、ローカルプロセスのみが接続できます。すべてのインターフェースに公開するには NOTION_MCP_BIND_HOST=0.0.0.0 を、192.168.1.5 のような特定の IP アドレスに公開するにはそのアドレスを設定してください。バインド先にかかわらず、ベアラーは必須です。

常時ベアラーが信頼境界となります。 /mcp エンドポイントには DNS リバインディング対策が組み込まれておらず、OAuth の登録／トークンエンドポイント（/register、/token、/revoke）の CORS 設定は許可的です。ネットワークと Notion ワークスペースとの間にある唯一の防御として、ベアラー、または OAuth のユーザーごとのベアラーを扱ってください。ループバックのみのデプロイでも、ベアラーを設定したままにしてください。このサーバーを信頼できるネットワークの外に公開する必要がある場合は、TLS とオリジンチェックを処理するリバースプロキシの背後に配置してください。

複数ユーザー／リモート利用には OAuth モードを使用してください。 OAuth ではユーザーごとのベアラーによる認証が行われるため、OAuth モードでは NOTION_MCP_BEARER は不要です。共有デプロイには、OAuth のユーザーごとの ID モデルが適しています。静的トークンとベアラーの組み合わせは、単一オペレーターによるセルフホストを想定しています。

file:// によるアップロードは stdio のみ対応です。 create_page、append_content、replace_content、update_section、または update_page.cover に渡された、file:// URL を含む Markdown は HTTP 経由では拒否されます。ローカルファイルを使うワークフローでは stdio モードを使用してください（create_page_from_file も stdio のみ対応です）。または、ファイルを HTTPS URL でホストし、その URL を Markdown 内で使用してください。

Markdown を優先する理由

Notion 公式の MCP npm パッケージは、生の API JSON を返します。ブロックオブジェクトは深くネストされており、各ブロックに約 120 トークン分のメタデータが含まれます。他のサーバーは Markdown に変換しますが、対応するブロックタイプはごく一部に限られ、コールアウト、トグル、テーブル、数式などが黙って破棄されます。

easy-notion-mcp は、エージェントがすでに使い慣れている標準の GFM Markdown を使用します。新たに覚えることも、独自のタグ構文も、組み立てるブロックオブジェクトもありません。エージェントが Markdown を記述し、easy-notion-mcp が Notion のブロック API との変換を処理します。逆方向の変換にも対応しており、24 種類のブロックタイプが保持されます。

これにより、エージェントは既存のコンテンツを編集できます。ページを読み取り、Markdown を取得し、文字列を変更して書き戻します。このサーバーが表現するブロックタイプでは、対応する書式と構造が保持されます。既知の欠落や劣化については、以下に記載しています。エージェントは、コードを編集するのと同じように、テキストとして Notion ページを編集できます。

easy-notion-mcp の仕組み

ページ — Markdown を記述して読み取ります。

create_page({
  title: "Sprint Review",
  markdown: "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only"
})

読み戻すと、同じ Markdown が返されます。

read_page({ page_id: "..." })

{ "markdown": "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only" }

文字列を変更して replace_content を呼び出せば完了です。または、見出し名を指定して update_section で単一のセクションを対象にできます。あるいは、ページの残りに触れずに find_replace で必要な箇所だけを置換できます。create_page または update_page で、ページに絵文字のアイコンやカバー画像を設定することもできます。

データベース — シンプルなキーと値のペアを記述します。

add_database_entry({
  database_id: "...",
  properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})

プロパティタイプオブジェクトや、{ select: { name: "Done" } } のようなネストされたラッパーは不要です。easy-notion-mcp は実行時にデータベーススキーマを取得し、自動で変換します。エージェントが { "Status": "Done" } を渡せば、あとは easy-notion-mcp が処理します。

エラーは修正方法を示します。 見出し名が間違っている場合は、利用可能な見出しを返します。ページが見つからない場合は、そのページをインテグレーションと共有するよう案内します。フィルターが正しくない場合は、先に get_database を呼び出すよう案内します。エージェントはユーザーに助けを求めずに、自ら修正できます。

複雑なコンテンツにも対応します。 トグル内のネストされたトグル、複数のコンテンツタイプが混在するカラム（リスト＋コードブロック＋引用）、深いリストのネスト、完全な Unicode（日本語、中国語、アラビア語、絵文字）は、往復変換のテストで検証されています。update_section の見出し検索では大文字と小文字が区別されず、見つからない場合は利用可能な見出しが返されます。add_database_entries は一部の失敗を処理し、成功したエントリと失敗したエントリを別々に返すため、エージェントは失敗したエントリだけを再試行できます。

easy-notion-mcp が提供するツール

easy-notion-mcp には、7 つのカテゴリにわたる、個別に名前が付けられた 43 個のツールが含まれています（HTTP 経由では 42 個で、stdio 専用の create_page_from_file は含まれません）。ツールの説明には安全性に関わる重要な動作が記載されており、Markdown 構文、警告の形式、プロパティのページネーション、update_data_source の例など、より詳しい参考情報を提供する MCP リソースも案内しています。

ページ（20 個のツール）

破壊的なツールでは、事前確認として dry_run: true を指定できます。ドライランでは、ローカルの file:// Markdown アップロードをアップロードまたは検証しません。これを行うと Notion へのアップロードが作成されるためです。ローカルファイルの場合は、HTTPS URL を使用するか、ドライランを行わずに実行してください。 replace_content のドライランでは Markdown を変換し、翻訳に関する警告を返しますが、Notion の更新エンドポイントを呼び出さないため、Notion 側の unmatched_blocks フィールドや truncated フィールドは表示されません。

restore_toggle は意図的に ID ベースになっています。archive_toggle が返すアーカイブ済みブロック ID を渡してください。Notion は、タイトル検索のためのアーカイブ済み子要素の列挙や、read_page include_archived のワークフローを提供していないため、タイトルによる復元はできません。

ナビゲーション（3 個のツール）

list_pages の各行は id、title、created_time、last_edited_time を返すため、エージェントはページごとに個別に問い合わせなくても、アクティブなページと古いページを見分けられます。タイムスタンプは Notion から直接取得され、分単位に丸められます。また、last_edited_time はページの内容やプロパティが編集されると更新されます。search は last_edited を日付のみで返す一方、list_pages は last_edited_time を完全な ISO-8601 タイムスタンプで返すという、意図的な違いに注意してください。

データベース（9 個のツール）

データベースの書き込みツールでは、未定義のプロパティ名やサポートされていないプロパティ型は、黙って無視せず、明確なエラーを返します。 プロパティ名と型を確認するため、最初に get_database を呼び出してください。書き込みでサポートされるプロパティ型は、title、rich_text、number、select、multi_select、date、checkbox、url、email、phone、status、relation、people です。people には、ユーザー ID の文字列 1 つ、またはユーザー ID の配列を渡してください。計算される型（formula、rollup、unique_id、created_time、last_edited_time、created_by、last_edited_by）は Notion によって設定され、API 経由では設定できません。files、verification、place、location、button への値の書き込みも拒否されます。リレーションへの書き込みには、ページ ID の文字列 1 つ（"Projects": "page-id"）または配列（"Projects": ["id-a", "id-b"]）を渡してください。空の配列を渡すとリレーションが解除されます。

easy-notion-mcp はデータベースのスキーマを取得し、値を Notion のプロパティ形式にマッピングして、エージェントから { "Status": "Done" } のようなシンプルなキーと値のペアが渡された場合に型変換を自動的に処理します。一括操作中の不要な API 呼び出しを避けるため、スキーマは 5 分間キャッシュされます。

ビュー（6 個のツール）

コメント（2 個のツール）

ユーザー（2 個のツール）

サーバー（1 個のツール）

ファイルパスまたは設定のエラーで原因がわからない場合は、get_config を使用してください。create_page_from_file はワークスペースのルート内のパスのみを受け付け、パスがルート外にある場合は、解決されたルートを示して拒否するようになりました。get_config を使えば、推測することなくルートを直接確認できます。HTTP モードではワークスペースのルートは適用されないため、パスフィールドは null になり、ステータスは not_applicable になります。サーバーが HTTP クライアントにホストのパスを報告することはありません。

どのような MCP リソースを利用できますか？

MCP リソースをサポートするクライアントは、すべてのリファレンス資料を各ツールの説明に読み込まずに、必要に応じて以下のドキュメントを参照できます。

easy-notion-mcp がサポートするブロックタイプ

easy-notion-mcp は、標準的な Markdown 構文に、トグル、カラム、コールアウトなど Notion 固有のブロック向けの規則を拡張した形式を使って、24 種類の Notion ブロックタイプをサポートします。エージェントは使い慣れた Markdown を記述し、easy-notion-mcp が Notion のブロック形式との相互変換を処理します。

標準的な Markdown

Notion 固有の構文

改行と collapse_soft_wraps

デフォルトでは、段落内の単一の改行はそのまま書き込まれます。そのため、固定幅でハードラップされた Markdown（ほとんどのリポジトリで一般的な形式）では、その改行が維持された状態で Notion に取り込まれます。このデフォルトに変更はありません。

Markdown 書き込みツールはすべて、省略可能な collapse_soft_wraps: true を受け付けます。これを指定すると、代わりに CommonMark のソフトラップのセマンティクスが適用され、段落内の単一の改行がスペースになります。そのため、ハードラップされたファイルは、流れるような段落として取り込まれます。どちらのモードでも、空行はブロックの区切りとして維持され、フェンス付きコードブロックには影響しません。

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --collapse-soft-wraps

Notion から読み取ったコンテンツを再アップロードする場合は使用しないでください。意図的な改行が失われます。

明示的なハード改行（末尾のバックスラッシュまたは末尾のスペース 2 つ）は、このオプションの設定にかかわらず同じように動作しますが、書き込み方法によって結果が異なります。

この違いはインポート方法によるものであり、collapse_soft_wraps によるものではありません。

タイトルと先頭の H1 の重複

create_page と create_page_from_file は、省略可能な strip_leading_h1: true を受け付けます。これを指定すると、ドキュメントの先頭にある H1 が削除されます。そのため、title に指定したものと同じ見出しで始まるファイルでも、同じ見出しがページに 2 回表示されることはありません。この設定が適用されるのは、変換後の最初のトップレベルブロックが通常の（トグル可能ではない）heading_1 の場合のみで、デフォルトは false です。

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --strip-leading-h1

create_page、create_page_from_file、append_content、replace_content、update_section、update_toggle は、不要な場合に block_map を省略するための return_block_map: false を受け付けます。デフォルトは引き続き true で、変更はありません。

書式を保持したままページを読み取り、書き換えることはできますか？

はい。このサーバーが表現する Markdown の規則に対応しています。24 種類のブロックタイプでラウンドトリップに対応しています。既知の未対応項目や劣化については文書化されており、その多くは明示的な警告とともに報告されます。

read_page は、create_page が受け付ける Markdown の規則を返します。見出し、リスト、テーブル、コールアウト、トグル、カラム、数式、ページメンションに対応しています。

ページに、このサーバーではまだ表現できない Notion ブロックタイプ（synced_block、child_database、child_page、link_to_page など）が含まれている場合、read_page は、除外されたブロックの ID とタイプを列挙するコード omitted_block_types を含む warnings フィールドを返します。その Markdown を replace_content で書き戻すと、これらのブロックは削除されるため、この警告によってエージェントは安全でない書き換えを避けられます。インラインのページメンションには @[Title](notion-url) を使用します。これは link_to_page ブロックタイプとは別の構成要素です。

Notion AI の議事録ブロック（非推奨の transcription を含む）は、タイトル、任意の録画タイムスタンプ、## Summary／## Notes セクションを含む合成トグルとしてレンダリングされます。トランスクリプトは、read_page include_transcript: true の場合にのみ含まれます。これらのレンダリングされた読み取りでは、Markdown を書き戻すとネイティブの議事録ブロックが通常のブロックに置き換わることを示すため、read_only_block_rendered 警告が出力されます。

警告では報告されない劣化もあります。replace_content の処理では、ブックマークと埋め込みは URL のみで書き込まれます（これらには警告が出ます）が、file、audio、video ブロックは警告なしに URL のみに置き換えられます。下線と色付きテキストの注釈は Markdown では表現されず、読み取り時と書き込み時に警告なしで削除されます。

easy-notion-mcp を使うと、エージェントはページを読み取り、Markdown 文字列を変更して、対応している書式、構造、コンテンツを保持したまま書き戻せます。フォーマット変換はありません。ブロックの再構築もありません。エージェントは、テキストとしてコードを編集するのと同じように Notion ページを編集できます。

find_replace と replace_content の違いは何ですか？

easy-notion-mcp は、用途に応じた 3 つの編集方法を提供します。

• replace_content — ページ上のすべてのコンテンツを新しい Markdown に置き換えます。ページ全体を書き換える場合に最適です。
• update_section — 見出し名で特定した単一のセクションを置き換えます。デフォルトでは、置換する Markdown に見出しが含まれ、セクション全体が置き換えられます。preserve_heading: true（または CLI の --preserve-heading）を渡すと、既存の見出しブロック ID、テキスト、タイプ、コメント、トグル可能な状態を保持したまま、セクション本文のみを破壊的に置き換えます。
• find_replace — ページ上の任意の場所にある特定のテキストを検索して置き換え、その他のすべてのコンテンツと添付ファイルを保持します。ピンポイントの編集に最適です。

破壊的な編集の前に、変更を加えずに事前確認の応答を得たい場合は、MCP ツールで dry_run: true を、CLI で --dry-run を渡してください。

easy-notion-mcp はデータベースをどのように扱いますか？

easy-notion-mcp は、Notion の複雑なプロパティ形式を抽象化する 9 つのデータベースツールを提供します。エージェントは { "Status": "Done", "Priority": "High" } のようなシンプルなキーと値のペアを渡します。easy-notion-mcp は実行時にデータベースのスキーマを取得して 5 分間キャッシュし、自動的に Notion のプロパティ形式に変換します。

easy-notion-mcp は、型付きスキーマを使用したデータベースの作成と更新、フィルターとソートを使用したクエリ、さらに add_database_entries による一括操作（1 回の呼び出しで複数行を追加）に対応しています。

Cookbook：独自のエージェント向けレシピ

これらのレシピでは、独自のエージェントを Notion に接続します。インテリジェンスを担うのはエージェントであり、easy-notion-mcp は既存の MCP ツールを通じて決定論的な接続処理を提供するため、2 回目のインストールなしで必要なときにレシピを実行できます。無料で、自由に利用できます。独自のエージェント、独自のトークン、OAuth 不要の API トークン設定、無料プランでのデータベースクエリを利用できます。

これらの手順は、MCP ツールまたは同等のツールが有効になっている場合の claude.ai コネクターで実行できます。レシピ 2 は skills/easy-notion-cli/ の easy-notion CLI スキルでも実行できます。レシピ 1 には create_database、search_in_page によるソースブロックの検索、構造化された重複排除フィルターが必要ですが、現在の CLI ではこのワークフロー全体を実行できません。Claude Code エージェントは skills/notion-recipes/ の運用スキルを使用できます。

レシピ 1：会議メモからアクションアイテムを作成する

このレシピでは、会議メモのページまたは貼り付けたメモを、アクションアイテムデータベースの重複のない行に変換します。ツールの実行順序は、最初に 1 回 create_database を実行し、その後、実行ごとに、ソースがページの場合は read_page、各アイテムのソースブロック ID を特定するために search_in_page、候補アイテムごとに Item Key の完全一致フィルターを指定して query_database、新しい行を追加するために add_database_entry または add_database_entries、最後に確認のため query_database です。

実際に動作を確認した結果、計画会議から 5 行が作成されました。担当者や期日が不明な場合は、Source ではなく Flags のマルチセレクトに保存しました。{"property":"Item Key","rich_text":{"equals":"38bbe876-242f-81f1-97b7-df935d050a24:38bbe876-242f-81c9-86c6-d9a792fc70b7"}} という query_database フィルターを指定すると、1 行だけが返されました。同じメモに対して 2 回実行しても、行数は 5 のままで、重複はありませんでした。会議名でフリーテキスト検索すると Source も検索対象となるためすべての行が返されました。そのため、このレシピでは重複排除に Item Key の完全一致フィルターを使用します。

安全性の境界：Item Key にアクションの文言ではなく、ソース行の安定した Notion ID（<pageId>:<blockId>）を保存するため、レシピ 1 は再実行しても安全で、冪等性があります。

claude.ai コネクタユーザー向けコピー＆ペースト、レシピ 1

Use the enabled easy-notion or Notion connector tools to turn my meeting notes into an Action Items database.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Meeting notes page or pasted meeting notes: <MEETING_NOTES_PAGE_OR_TEXT>
- Parent page for the database, if a new database is needed: <PARENT_PAGE>
- Existing Action Items database, if one already exists: <DATABASE_NAME_OR_ID>

If an Action Items database does not already exist, create one with these properties:
- Name: title
- Item Key: rich_text
- Owner: rich_text
- Due: date
- Status: status
- Flags: multi_select
- Source: rich_text

Read the meeting notes or use the pasted notes. Extract only discrete action items. For each item, derive:
- Name: the action text
- Owner: the named assignee, or blank
- Due: the stated date as ISO YYYY-MM-DD, or blank
- Item Key: the source line's stable identity, formatted as <sourcePageId>:<sourceBlockId>
- Source: the meeting title plus date, with no flags stashed here
- Status: Not started
- Flags: add needs-owner if no owner, and needs-due if no due date

Resolve sourceBlockId with search_in_page. read_page returns markdown without block IDs. For a Notion-page source, call read_page to extract items, then for each item call search_in_page with a verbatim, distinctive substring of that item's original source line. Use the matches[].block_id whose text is that source line. If several blocks match, use a longer verbatim substring to isolate one block. For pasted notes, first save them as a Notion page with create_page, then proceed through search_in_page. Do not rely on block IDs from create_page, which returns only {id,title,url}. If one source line contains multiple distinct actions, append a stable ordinal suffix in source order, such as :1 or :2, to keep keys unique.

Before inserting each item, dedupe with an exact Item Key filter:
{"property":"Item Key","rich_text":{"equals":"<that item's key>"}}

If the query returns no results, insert the row with simple key-value properties. If it returns a result, skip that item. Do not dedupe with free-text database search, because text search also scans Source and can false-match every row from the same meeting.

After inserting, query the database and summarize the rows created and skipped.

Re-running is safe and idempotent because the exact Item Key filter uses the source line's stable Notion identity, not the action wording.

レシピ 2：一括編集、検索と置換、修復

このレシピでは、エージェントが Notion の標準的な制限を超えて反復処理できる 2 つの対象、データベースプロパティの修復とページ本文の検索と置換を扱います。データベースを修復する場合の実行順序は、get_database、すべての行を対象とした query_database、正規化マップの作成、修正が必要な行に対する update_database_entry、その後の再クエリです。ページ本文の場合の実行順序は、dry_run: true を指定した find_replace、replace_all: true を指定した find_replace、確認のための read_page です。

実際に動作を確認したデータベースの修復では、Eng と engineering が混在していた 4 行を一貫した 1 つのオプションに正規化し、関係のない行は変更しませんでした。実際に動作を確認したページ編集では、段落と見出し本文にある 4 か所を置換しました。注意点：セレクトとステータスのオプションは大文字と小文字を区別せずに照合され、書き込み時には既存のオプションのうち最も古いものの大文字・小文字の表記に統一されます。小文字のバリエーションがすでに存在する場合、大文字で書き込んでも既存の小文字のオプションが再利用されます。特定の大文字・小文字表記にするには、新しい表記を書き込むのではなく、Notion の UI でオプションの名前を変更してください。

claude.ai コネクタユーザー向けコピー＆ペースト、レシピ 2

Use the enabled easy-notion or Notion connector tools to repair Notion database rows or replace repeated text in a Notion page.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Target database for property repair: <DATABASE_NAME_OR_ID>
- Property to normalize: <PROPERTY_NAME>
- Normalization map, for example {"Eng":"Engineering","engineering":"Engineering"}
- Target page for find-replace, if needed: <PAGE_NAME_OR_ID>
- Find text and replacement text, if needed: <FIND_TEXT> -> <REPLACE_TEXT>

For database property repair:
1. Get the database schema so you know the exact property names. If select or status options are missing from the schema, query live rows and read the current values from the results.
2. Query the database rows. If the database is large, page through all results in a loop.
3. Build or use the normalization map I provide.
4. For each row whose property value needs fixing, update that row with a simple key-value map such as {"<PROPERTY_NAME>":"<CANONICAL_VALUE>"}.
5. Re-query the database and summarize how many rows changed and which values remain.

Important caveat: select and status option matching is case-insensitive, and writes snap to the earliest-existing option's casing. If a lowercase variant already exists, writing a capitalized version may reuse the lowercase option. To force specific casing, I need to rename the option in Notion's UI.

For page-body find-replace:
1. Run a dry-run find-replace with replace_all enabled and report the match count before changing anything.
2. If the match count is expected, run find-replace with replace_all enabled.
3. Read the page afterward and verify the replacement.

セキュリティとプロンプトインジェクションについて

easy-notion-mcpには、本番環境へのデプロイ向けに2層のセキュリティ対策が備わっています。

プロンプトインジェクション対策： Markdownの読み取りレスポンス（read_page、read_section、read_block、read_toggle）には、Notionのデータを指示ではなくコンテンツとして扱うようエージェントに指示するコンテンツ通知のプレフィックスが含まれます。search_in_pageは生のスニペット／テキストを返すため、同様に扱う必要があります。これにより、ページのコンテンツがエージェントの動作を誘導するリスクを軽減できますが、最終的な動作はモデルとクライアントによって異なります。ワークスペースを管理している場合は、NOTION_TRUST_CONTENT=trueを設定してMarkdownの通知を無効にできます。

URLのサニタイズ： javascript:、data:などの安全でないURLプロトコルは除去され、プレーンテキストとして表示されます。許可されるのはhttp:、https:、mailto:のみです。

安定性とバージョニング

easy-notion-mcpはセマンティックバージョニングに従います。 1.0.0以降、公開契約は追加のみで凍結されています。ツール名、ツールの入力スキーマ、ツールの戻り値の形式、独自のMarkdown規約、警告コードの語彙は、将来の2.0リリースまでは破壊的な変更を行いません。追加の変更（新しいツール、新しいオプションパラメーター、新しいオプションのレスポンスフィールド、新しい警告コード）は破壊的変更ではなく、マイナーリリースで提供される可能性があります。

この凍結の対象外となる領域が2つあります。OAuth／HTTP認証の契約は実験的なものであり、セキュリティ態勢の成熟に合わせて変更される可能性があります。また、easy-notion CLIは1.0未満で、まだ対象に含まれていません。契約の詳細とリリースごとの履歴については、CHANGELOGを参照してください。

よくある質問

easy-notion-mcpは公式のNotion MCPサーバーとどう違いますか？

公式のNotion MCP npmパッケージ（@notionhq/notion-mcp-server）は、変更されていないNotion JSONを返す生のAPIプロキシです。そのため、ページの読み取りにかかるレスポンストークンは、easy-notion-mcpのMarkdownを使用した場合の約6～7倍になります。easy-notion-mcpはすべてを標準のGFM Markdownに変換するため、エージェントがすでに理解している形式で扱えます。また、文書化された往復変換時の注意点を伴う24種類のブロックタイプをサポートし、プロンプトインジェクション対策も備えています。Notionはこれとは別に、独自のHTMLタグベースのMarkdown形式を使用するホスト型のリモートMCPサーバー（OAuthベース）も提供していますが、easy-notion-mcpは標準のMarkdown構文を使用します。

easy-notion-mcpはどのMCPクライアントで使えますか？

easy-notion-mcpは、Claude Desktop、Claude Code、Cursor、VS Code Copilot、Windsurf、OpenClawなど、MCP互換のあらゆるクライアントで動作します。stdioトランスポート（APIトークン）とHTTPトランスポート（OAuth）の両方をサポートしています。各クライアント向けのコピーして貼り付けられる設定については、セットアップ手順を参照してください。

easy-notion-mcpはファイルのアップロードをサポートしていますか？

はい。easy-notion-mcpは、Markdown構文でfile:///プロトコルを使用したファイルのアップロードをサポートしています。画像は![alt](file:///path/to/image.png)で、ファイルは[name](file:///path/to/file.pdf)でアップロードできます。

easy-notion-mcpはネストされたコンテンツや複雑なコンテンツを扱えますか？

はい。トグル内にネストされたトグル、異なる列に混在するコンテンツタイプ（リスト、引用ブロック、コードブロック）を含むカラム、ネストされた箇条書きリストと番号付きリスト、日本語、中国語、ロシア語、アラビア語、絵文字を含む完全なUnicodeサポートについて、サポート対象の形式を対象とした往復変換テストを実施しています。

easy-notion-mcpはバッチ操作で一部が失敗した場合も処理できますか？

はい。add_database_entriesは、succeeded配列とfailed配列を分けて返します。1つのエントリーの検証に失敗しても、他のエントリーは作成されます。エージェントはバッチ全体を再送信せず、失敗したエントリーだけを再試行できます。

コミュニティ

discord.gg/S8cghJSVBUでコミュニティDiscordに参加できます。#easy-notion-mcpチャンネルではセットアップに関する質問や設計についての議論を行っており、サーバーのほかの場所では、作品の紹介や一般的な会話ができます。バグや具体的な機能リクエストについては、引き続きGitHubのissueが正式な窓口です。

コントリビュート

GitHubでのイシューやプルリクエストを歓迎します。

ライセンス

MIT