はじめに
こんにちは、ネクストモードの鮎澤です。
Notionの開発者プラットフォームが公開され、Notion CLIとNotion Workers（以下、ワーカー）が利用できるようになりました。
ただ、開発者プラットフォームとワーカーの関係、使い方など全体像を掴みきれていない方もいらっしゃるのではないかと思います。（私は概要を理解するのに時間がかかりました……）
そこで本ブログではワーカーを中心に、開発者プラットフォームやそれに関わるツールなどを、なるべく分かりやすくご紹介していきます。また、Notion CLIのインストールからワーカーの作成・デプロイ、さらに筆者が躓いた内容もまとめてみました。
概要レベルでも把握したい方はぜひ最後まで読んでいただけると嬉しいです。
より詳細な情報を確認されたい場合は、開発者向けドキュメントをご覧ください。
開発者プラットフォームとは
開発者プラットフォームとは、その名のとおり開発者やエージェントがNotion上で機能を構築するための基盤です。外部データをワークスペースに同期したり、独自のコードをNotionのインフラ上で動かしたりできます。
その開発者プラットフォームに含まれているツールとして、Notion CLIやワーカー、他にも外部エージェントAPIやエージェントSDKがあり、これらの機能を使ってNotionを操作したり、Notionを他のシステムに接続するコードを実行したりできます。
ここからは4つの機能についてそれぞれ簡単にご紹介します。
Notion CLI ntn（パブリックベータ版）
Notion CLIはコマンドラインから、Notion上のコンテンツの読み取りと書き込みなどを行えるツールです。Notion ワークスペースの画面上で操作するよりも、コマンドラインでNotion上のコンテンツを操作したいときに利用します。
Notion CLIはどのプランでも利用可能ですが、後述のワーカーのデプロイと管理で利用する場合は、ビジネスプランまたはエンタープライズプランが必要です。
ワーカー（パブリックベータ版）
ワーカーは独自のコードをNotion のサーバー上にデプロイできる、小さなNode/TypeScriptプログラムです。利用するにはビジネスプランまたはエンタープライズプランが必要です。ポイントとしてはMCPサーバーを立てる必要はなく、自身の端末でコーディングしデプロイすることができます。ワーカーの主な利用シーンは以下のとおりです。
- スケジュールに基づいて外部ツールの情報をNotion データベースに同期し、最新の状態に保ちたいとき
- Notion カスタムエージェントの標準では用意されていない接続先を指定し、読み取りや書き込みといった操作をしたいとき
- GitHubなどの外部サービスのWebhookをトリガーに、手動での操作を自動化したいとき
TypeScriptでコードを記述するため、明確な目的があり、ロジックベースで実行したい場合はワーカーを使ってみてください。
ワーカーを実行するにあたり、Notionクレジットを消費します。実行1回分の料金について公式ドキュメントを確認すると、「ワーカーは1回あたり通常$0.0023で実行」とありました。実行時の処理量や実行時間といったワーカーの作業量によって、料金（消費するクレジット量）は変動します。料金の詳細情報は以下の公式ドキュメントをご参照ください。
外部エージェントAPI（プライベートベータ版）
外部エージェントAPIは、自社が別のフレームワークで独自に開発したエージェントを、Notionに「ワークスペースの一員」として迎え入れられる仕組みです。たとえば社内向けに作り込んだサポート対応エージェントや、運用を自動化するために組んだエージェントを、Notionのエージェント一覧に並べて表示し、ワークスペース上で直接チャットしたり作業を任せたりできるようになります。
NotionにはClaudeやCodexといったパートナー製のエージェントがあらかじめ用意されていますが、外部エージェントAPIを使えば「自前のエージェント」も同じ土俵に乗せられる、というのがポイントです。NotionがトリガーやツールへのアクセスをAPI経由で提供してくれるため、エージェントはNotion上の他のメンバーと同じ画面・同じ流れの中で動けるようになります。
なお現時点ではプライベートベータ版での提供となっており、利用にはウェイトリストへの登録が必要です。
エージェントSDK（プライベートアルファ版）
エージェントSDKは、外部エージェントAPIとはちょうど逆方向のアプローチと考えると分かりやすいです。外部エージェントAPIが「外のエージェントをNotionに連れてくる」仕組みだとすれば、エージェントSDKは「Notionのカスタムエージェントを、外のツールから呼び出す」ための仕組みです。
たとえばCRMのボタンから商談レポートの作成を走らせたり、TeamsやDiscordに届いた問い合わせにワークスペースの情報をもとに回答させたり、Webサイトのチャットボットとして使ったり、といったユースケースが想定されています。TypeScript / JavaScript向けのSDKとして提供され、外部システムからNotionエージェントをプログラム的に起動できるのが特徴です。
こちらはプライベートアルファ版という、外部エージェントAPIよりもさらにアーリーな段階での提供です。気になる方はウェイトリストに登録して続報を待ちましょう。
ワーカーのデプロイ方法
ここではNotion CLIのインストールからワーカーの作成・デプロイ実行まで一通り紹介していきます。もし、何かしらのエラーで詰まった場合は、後半の方にトラブルシューティングの項目を記載したので、エラー解消のお役に立ちましたら幸いです。
前提
環境
OS：Windows 11 Pro
Visual Studio Code（以下、VSCode）：1.126.0
Node.js：v24.18.0（バージョン22以降推奨）
npm：11.16.0（バージョン10以降推奨）
Node.jsとnpmがインストールされていない場合は、以下コマンドを実行してください。インストールが完了したらPATH反映のためVSCodeを一度閉じ、再度起動します。
winget install OpenJS.NodeJS.LTS
その後、以下コマンドを実行してバージョンが表示されれば問題ありません。
node -v
npm -v
ワーカーを有効化
Notionワークスペースにログインし、管理者権限で 設定 → ワーカー から「ワーカーを有効化」をクリックして、有効化してください。有効化後のインターフェイスがタイミングによって、下図と異なる場合がございます。有効化時にエラー等のポップアップが表示されていなければ問題ないと思いますので、そのまま進めていきましょう。
Notion CLIインストールからログイン
はじめにNotion CLIをインストールしていきます。以下の公式ドキュメントを参考に、インストールしていきましょう。
といってもコマンド1つで終わります。VSCodeを開き、以下コマンドを実行してNotion CLIをインストールします。
winget install Notion.ntn
インストールが完了したら、VSCodeを一度閉じてから再度起動します。続いて以下コマンドを実行し、ntnのバージョンが表示されれば問題なくインストールが完了しています。
ntn --version
次にntnコマンドを使って、Notionへログインします。コマンドは ntn login です。コマンドを実行するとブラウザが立ち上がり、Notion CLIの承認画面が表示されるはずです。ターミナルとブラウザのverification codeが一致していることを確認し、ログインしたいワークスペースを選択して「承認」ボタンをクリックします。
ターミナル側を確認し、「Authenticated!」になっていれば問題ありません。
ワーカーの作成からデプロイ
以下の公式ドキュメントを参考に、ワーカーの作成からデプロイまで一通りやっていきます。任意ですがワーカー用のディレクトリを作成するとよいと思います。私は「C:\Users\<ユーザー名>\」の配下にNotion用のディレクトリを作成しました。ディレクトリ名は何でもいいので、notionでもnotion-testでもお好みで、かつ分かりやすい名前で作成してみてください。
本題に戻りまして、ワーカーを作成するには以下コマンドを実行します。
ntn workers new <任意のディレクトリ>
私は ntn workers new ayu-worker でコマンドを実行しました。すると以下の1つ（または2つ）を聞かれると思いますので、環境に合わせて選択してください。私の場合は、検証目的なので「Install dependencies?」は「yes」にしました。
- 「Install dependencies?」
この質問は、「このプロジェクトが必要とする依存パッケージ（ライブラリ）を今すぐインストールしますか？」ということを聞かれています。ワーカーのテンプレートには「動作に必要な外部パッケージの一覧」が package.json というファイルに書かれています。この質問に yes を選ぶと、その一覧をもとに npm install（または使用中のパッケージマネージャ）が自動実行され、node_modulesフォルダにライブラリ一式がダウンロードされます。
yes → 今すぐ依存パッケージをインストール。完了後すぐにワーカーを動かせる状態になります。
no → インストールをスキップ。プロジェクトのファイルだけが作られた状態になります。
- 「Initialize a git repository (yes/no)」
この質問は、「この新しく作るプロジェクトフォルダを、Git のバージョン管理リポジトリとして初期化しますか？」ということを聞かれています。yes/noを選択したときの挙動は以下にまとめています。Git管理までは不要の場合はnoで問題ないです。
yes → プロジェクトフォルダ内で git init 相当の処理が実行され、.gitという隠しフォルダが作られます。これでそのフォルダが Gitリポジトリになり、コードの変更履歴を記録（commit）したり、GitHubなどのリモートにpushしたりできるようになります。
no → Git 管理されない「ただのフォルダ」としてプロジェクトが作られます。あとから必要になれば、自分でフォルダに移動して git init を実行すれば、いつでも Git 管理を始められます。
インストールが完了すると、スターターファイル、TypeScriptの設定ファイル、および依存関係を含む新しいディレクトリが作られました。「ntn workers new ayu-worker」でコマンドを実行したので、「ayu-worker」というディレクトリ名になっています。
それでは、Next stepsに沿ってデプロイまでやっていきましょう。はじめに以下コマンドでディレクトリを移動します。
cd <ntn workers new で作成したディレクトリ名>
続いて以下のコマンドを実行してデプロイしましょう。Notion側へ何かしら変更が加わることはありませんので、ご安心ください。
ntn workers deploy
途中、ワーカー名を聞かれるので、そのままEnterを押してください。特に指定しない場合、ワーカー名はディレクトリ名と同じ（私の場合はayu-worker）になります。Toolsに「sayHello」が返ってくれば問題なくデプロイが完了しています。 
Notionワークスペースを開き、 設定 → ワーカー → すべてのワーカー の順にクリックすると、デプロイしたワーカーの一覧を確認することができます。
また、ターミナルで ntn workers usage を実行すると、ワーカー名やワークスペースID、クレジットの推定使用量を確認することができます。
本ブログはここまでのご紹介となります。より実践的な内容は今後ブログ化予定なのでお楽しみに。
トラブルシューティング
Q. デプロイを実行したときにエラーが出ます。対処方法を教えてください。
error: Failed to create worker (403 Forbidden WorkersCapabilityMissing):
This token does not have the ability to manage Workers. In an agent-computer
session, this usually means Notion Workers is not enabled for the workspace
or the workspace has not accepted the Workers terms. Ask a workspace owner
to enable Workers and accept the terms, then retry. A. Notionワークスペース上でNotion Workersを有効化していることを確認してください。無効化になっていた場合は有効化し、ターミナルで再ログイン（ ntn logout → ntn login ）すると解消する可能性があります。
Notion Workersを有効化しても、すでに発行済みのトークンには反映されません。一度ログアウトして入り直すことで、Workers権限を含む新しいトークンが発行されます。
Q. デプロイコマンドを実行したが、 error: Failed to upload source archive となります。原因を教えてください。
A. デプロイ時にファイルのアップロードでエラーになっています。 ntn workers deploy --verbose で詳細なログを確認し、エラーとなっている箇所を特定してください。
私のケースでは、最終的に「*.s3.us-west-2.amazonaws.com」へ到達できないことが原因でエラーが発生していました。ntn workers deploy を実行すると、Notion が管理する Amazon S3 のバケットへコード一式をアップロードする仕組みになっているため、この S3 エンドポイントへ通信できない環境では、アップロードの段階でデプロイが失敗してしまいます。
結論としては、「*.s3.us-west-2.amazonaws.com」との通信ができるようにしたことで、無事にエラーは解消されました。なお、接続先となる S3 バケットのドメインは利用者によって異なります。同じエラーに遭遇した場合は、まずは詳細なログでエラー箇所を確認し、必要に応じて社内の情報システム部門へ相談してみてください。
まとめ
開発者プラットフォームの全体像から、ワーカーをデプロイするための方法およびトラブルシューティングまでご紹介しました。
ワーカーは、カスタムエージェントだけではカバーしきれなかった連携を担ってくれるので、カスタムエージェントの活躍の幅が広がったように思います。もちろんカスタムエージェントを使わずとも、Notion上で今まで手動で行っていた作業を自動化することもできます。
2026年8月10日まで無料で試せるので、頭に浮かんでいるアイデアをワーカーにぶつけていきましょう！
参考
本文と重複するところもございますが本ブログを執筆するにあたり、参考にさせていただいた情報をこちらに記載しましたので、気になる方はご参照ください。
- Notion開発者プラットフォームとは？ - Notion(ノーション)ヘルプセンター
- Overview - Notion Docs
- Notionの開発者プラットフォームを使って構築しましょう
- Notion CLIを使用して、ターミナルからNotionを使用する - Notion(ノーション)ヘルプセンター
- ワーカーでカスタムコードを実行する（ベータ版） - Notion(ノーション)ヘルプセンター
- What are Notion Workers? - Notion Docs
- ワーカーの料金体系を理解する（ベータ版） - Notion(ノーション)ヘルプセンター
Notionについてのお問い合わせ
ネクストモード社は、日本で3社しかないNotion販売代理店です。(2025/12現在)
Notion導入を検討の際は是非下記からお問い合わせ頂けますと幸いです。
