notion

Notion

Notion ワークスペースで Notion API（https://api.notion.com/v1/、API バージョン 2025-09-03）を利用するためのツールです。ページやデータソースの検索、ページの読み取りと作成、データソースの行のクエリ、ブロックコンテンツの追加と編集、データベース／データソースのスキーマ管理、コメントの読み取りと投稿ができます。検索、読み取り、書き込み、スキーマ、コメント、ワークスペース間コピーに対応する 24 個のスクリプトがあります。このバージョンでは Notion のデータソースモデルを使用します。_データベース_は 1 つ以上の_データソース_を格納するコンテナで、_データソース_にはプロパティスキーマと行（ページ）が含まれます。

Notion 向けの独立した非公式コネクターです。Notion との提携、承認、後援を受けていません。「Notion」は、このコネクターが連携するサービスを特定する目的でのみ使用している、所有者の商標です。

使用する場面

• エージェントがコンテンツを検索または読み取りたい場合 — タイトルでページやデータソースを検索し、ページ、そのブロック本文、データソースのスキーマ、またはその行を読み取ります。
• エージェントがページやコンテンツを作成または編集したい場合 — ページ（データソース内の行またはサブページ）を追加し、プロパティを更新し、ブロックを追加するか、ブロックを編集／削除します。
• エージェントがデータソースをクエリしたい場合 — データソースの行をフィルタリングして並べ替えるか、単一ページのプロパティを読み取ります。
• エージェントがスキーマを管理したい場合 — データベースやデータソースを作成または更新し（プロパティの追加／名前変更／型変更／削除）、コメントを読み取るか投稿します。

セットアップ

これは agentskills.io スキルです。

コネクターがまだスキルとしてインストールされていない場合は、まず npx skills add zapier/connectors --skill notion（または使用するハーネス独自のスキルインストール方法）でインストールしてから、ここに進んでください。スキルのインストールでコピーされるのはこれらのファイルであり、依存関係ではありません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。代わりに、公開パッケージを依存関係として独自のプロジェクトにインポートしますか？その場合は、すでに npm install ですべてが解決されます。詳しくは references/use-as-sdk.md を参照してください。

代わりにリポジトリのソースそのものを確認したい場合（references/ の閲覧、このコネクターのテスト実行、またはコードの変更など）は、対象を絞った git clone について README.md を参照してください。

このコネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

使用環境...	読み込むもの
MCP 対応クライアント — ツールがすでに読み込まれている場合（例：mcp__notion__<tool>）や、自分でローカルサーバーを登録する場合（またはユーザーに登録を案内する場合）	references/use-as-mcp.md
ターミナル／サブプロセスにアクセスできる（node を実行できる）	references/use-as-cli.md
独自のコードのみを使用し、このパッケージを依存関係としてインポートする	references/use-as-sdk.md
ツールやターミナルにアクセスできず、このパッケージもインポートできない — Notion API を直接呼び出す独自のコードを作成する（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

copyPage は 2 つのスロット（source + target）を使ってワークスペース間でページをコピーします。それ以外のすべてのスクリプトは、単一の接続 notion を使います。

スクリプト	スクリプト名	接続先	説明
scripts/search.ts	search	notion	タイトルでページとデータソースを検索します（ID 解決のエントリーポイント）。
scripts/getPage.ts	getPage	notion	ID を指定してページのメタデータとプロパティ値を取得します。
scripts/getDatabase.ts	getDatabase	notion	データベースコンテナとデータソースの一覧を取得します。
scripts/getDataSource.ts	getDataSource	notion	データソースのプロパティスキーマ（名前、型、オプション）を取得します。
scripts/queryDataSource.ts	queryDataSource	notion	フィルターや並べ替えを指定して、データソースの行（ページ）をクエリします。
scripts/getBlockChildren.ts	getBlockChildren	notion	ページまたはブロックの子ブロック（本文コンテンツ）の一覧を取得します。
scripts/getBlock.ts	getBlock	notion	ID を指定して単一のブロックを取得します。
scripts/getPageAsMarkdown.ts	getPageAsMarkdown	notion	ページの本文コンテンツを Markdown 形式で取得します。
scripts/getPageProperty.ts	getPageProperty	notion	単一のページプロパティ値を取得します（ページネーション対応）。
scripts/listComments.ts	listComments	notion	ページまたはブロックの未解決コメントを一覧表示します。
scripts/listUsers.ts	listUsers	notion	ワークスペースのユーザー（メンバーとボット）を一覧表示します。
scripts/getUser.ts	getUser	notion	ID を指定して単一のユーザーを取得します。
scripts/getBotUser.ts	getBotUser	notion	現在のトークンに対応するボットユーザー（インテグレーションの識別情報）を取得します。
scripts/createPage.ts	createPage	notion	ページを作成します。データソース内の行（parent.data_source_id）またはサブページ（parent.page_id）を作成できます。
scripts/updatePage.ts	updatePage	notion	ページのプロパティ、アイコン、カバー、親（移動）、またはゴミ箱の状態（in_trash）を更新します。
scripts/appendBlockChildren.ts	appendBlockChildren	notion	ページまたはブロックの末尾にコンテンツブロックを追加します。
scripts/updateBlock.ts	updateBlock	notion	単一のブロックのコンテンツを更新するか、アーカイブします。
scripts/deleteBlock.ts	deleteBlock	notion	ブロックを削除します（ゴミ箱に移動します。元に戻せます）。
scripts/createDatabase.ts	createDatabase	notion	初期データソーススキーマを指定して、ページ内にデータベースを作成します。
scripts/updateDatabase.ts	updateDatabase	notion	データベースコンテナのタイトル、アイコン、カバー、親、インライン表示、ゴミ箱の状態を更新します。
scripts/createDataSource.ts	createDataSource	notion	既存のデータベースに新しいデータソース（スキーマ）を追加します。
scripts/updateDataSource.ts	updateDataSource	notion	データソースのスキーマを更新します（プロパティの追加、名前変更、型変更、削除）。
scripts/createComment.ts	createComment	notion	ページにコメントを追加するか、既存のスレッドに返信します。
scripts/copyPage.ts	copyPage	source、target	あるワークスペースから別のワークスペースにページ（タイトルとトップレベルのブロック）をコピーします。Notion 接続が 2 つ必要です。

曖昧さの解消と拒否

書き込み前に曖昧さを解消します。 名前で検索したページまたは行（例：search で見つけたページの更新、queryDataSource で見つけた行の更新）に書き込む前に、大文字と小文字を区別しない完全一致のタイトルの数を数えます。

• 一致が1件のみ — その対象に対して操作します。必要以上に確認を求めないでください。曖昧さのない一致が1件なら、それが回答です。
• 同数で2件以上 — 停止します。候補を識別できるフィールド（parent、url、last_edited_time）とともに、該当する候補を列挙し、どれを指しているのかユーザーに尋ねてください。任意に選んだり、すべてに書き込んだりしないでください。

サポートされていない操作 — その旨を伝えて停止し、別のツールで代用しないでください。 このカタログでは、意図的に次の操作をサポートしていません。

• 完全に削除すること。 すべてゴミ箱への移動／復元です。ページは updatePage の in_trash、ブロックは deleteBlock（元に戻せます）で処理します。完全削除はできません。
• データベースまたはデータソース全体を削除すること。 そのためのツールはありません。代わりにすべての行をゴミ箱に移動して、削除を再現しないでください。
• ワークスペースのメンバーや権限を管理すること（ユーザーの招待、ロールの変更、共有など）。listUsers／getUser は読み取り専用です。
• データベースビューを作成または管理すること。 ビューはAPIで公開されていません。

これらの操作を依頼された場合は、サポートされていないことをユーザーに伝えて停止してください。代用のために無関係なツールを使わないでください。

認証

すべてのシェイプは、シークレットではなく、1つの接続 セレクター（[<resolver>:]<value> 形式の文字列）を使って認証します。すべてのコネクターで zapier:<connection-id>（Zapier 管理の認証。Zapier の認証、再試行、ガバナンスのレイヤーを経由します）が使用できます。また、一部のコネクターでは直接トークン用のリゾルバーも1つ以上使用できます（名前と数はコネクターによって異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>: の接頭辞は省略可能です。値だけを指定した場合は、その値を最初に受け取るリゾルバーに渡されます。UUID形式の値だけを指定した場合は、必ず zapier: が受け取ります。各スクリプトでは、必要な接続と、受け入れるリゾルバーを宣言します。接続を渡す正確な構文と、このコネクターのリゾルバー一覧の確認方法はシェイプによって異なります。上で読み込んだリファレンスを参照してください。

すでに設定済みのものを確認しますか？確認のために環境変数の値を出力しないでください。env または env | grep <name> は名前と値を出力するため、値が設定されていると有効な認証情報がトランスクリプトに漏れる可能性があります。名前だけを確認するには（env | cut -d= -f1 | grep -i <name>）、または既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

接続がまだありませんか？次のいずれかを選び、接続を取得する際はリファレンスに記載されている手順に従ってください。ユーザーが接続 ID やトークンをすでに覚えているかのように、単に尋ねることは避けてください。

	読み込む
認証情報を直接渡す	references/use-without-zapier.md
Zapier 接続を経由する	references/use-with-zapier.md

出力形式

各スクリプトは { data, meta } のエンベロープを返します。

• data — スクリプトの結果です（outputSchema で宣言されている形式。スクリプト固有の正確なスキーマの確認方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除された項目はありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスが data から除外されています。スクリプトが API から返したものの、outputSchema で宣言されていないフィールドです。必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証がバイパスされ、data は未検証のスクリプト出力そのものです。

除外されたフィールドの確認／skipOutputDataValidation。 未検証の生の結果を受け取るには、出力検証を無効にしてください（正確な構文はスクリプトの形式によって異なります。上で読み込んだリファレンスを参照してください）。入力検証はスキップされません。

結果の絞り込み／filterOutputData。 大きな結果から必要なフィールドだけを取り出すには、data を後処理する jq 式を渡してください（正確な構文はスクリプトの形式によって異なります）。jq は { data, meta } のエンベロープではなく、data のみに対して実行されるため、data を起点に記述してください（出力スキーマを確認するには、スクリプトの --help またはお使いの形式に相当するものを実行してください）。変換後の値が data に置き換わり、meta は保持されます。また、結果は出力スキーマに対して再検証されません。

参考資料

該当する領域の作業を始める前に、対応する参考ファイルを読み込んでください。

参考資料	対象範囲	読み込むタイミング
references/notion-api-gotchas.md	バージョニングと2025-09-03のデータソースモデル、認証／共有、エラーエンベロープとコード表、レート制限、サイズ制限、ページネーション、ID／URL形式、アーカイブ／ゴミ箱、タイトルのみの検索、25件の参照の切り捨て。	エラーや 404 のデバッグ、リストのページネーション、IDの解決、データベースとデータソースの違いについて検討するとき。
references/notion-blocks.md	型付きブロックオブジェクト、一般的なブロックタイプ、rich_text の形式、子要素の追加（制限とネスト）、updateBlock ではブロックのタイプを変更できない理由。	ページコンテンツの作成や編集を行うとき — appendBlockChildren、createPage（children）、updateBlock。
references/notion-properties.md	プロパティスキーマオブジェクトとタイプ一覧、およびタイプごとのページプロパティ値の形式。	スキーマの定義（createDatabase、createDataSource）やプロパティ値の書き込み（createPage、updatePage）を行うとき。
references/notion-query.md	filter オブジェクト（単一条件と複合条件の and／or）、タイプごとの条件、sorts 配列、結果数の上限10,000件。	filter またはソートを指定して queryDataSource を呼び出すとき。