Notion

Notion MCP サーバー

AI アシスタントから、複数のワークスペースにまたがって、ひとつのサーバーを通じてNotionのワークスペースを検索、読み取り、書き込みできます。ページは Markdown 形式で扱い、データベースをクエリして列ごとに件数を集計できます。保存済みビュー、ユーザー、コメント、ファイルも扱えます。ページ、行、列、データベースを作成し、プロパティや本文を編集し、コメントを追加し、ファイルをアップロードして、ページを Notion のゴミ箱に移動できます（30 日間保管されます。restore_pageで復元できます）。どのツールもmoneyではありません。

必要なもの： ワークスペースごとの Notion インテグレーション、そのトークンを保存した専用ファイル、そしてインテグレーションと共有したトップレベルページです。インテグレーションから見えるのは、共有したページのみです。アップロードできるファイルの上限は 20 MiB です（Notion の Free プランでは 5 MiB）。

できること

• 「仕事用ワークスペースで Q3 ロードマップのページを探して、要約してください。」
• 「Tasks データベースの行は、ステータスごとに何件ありますか？」
• 「Due this week ビューを表示してください。」
• 「Reading List に『Thinking in Systems』をステータス To read、タグ Books で追加してください。」
• 「Onboarding ページで、『Slack』をすべて『Mattermost』に置き換えてください。」
• 「Contracts データベースの Client SRL 行に添付された PDF をダウンロードしてください。」

インストール

Claude Code の場合：

claude mcp add notion -e NOTION_TOKENS_DIR="<path to Notion tokens folder>" -- npx -y @foreverworks/mcp-notion

Claude Desktop（Settings、Developer、Edit Config）や、ほかの多くのクライアントでは、同じコマンドを JSON として読み込みます。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-notion"],
      "env": {
        "NOTION_TOKENS_DIR": "<path to Notion tokens folder>"
      }
    }
  }
}

それぞれ、Node 22.19 以降で公開済みのパッケージを実行します。VS Code と Claude Desktop バンドルでは、サーバーの追加時にNOTION_TOKENS_DIRの入力を求められます。一方、Cursor は環境変数（${env:NOTION_TOKENS_DIR}）から読み込むため、Cursor の起動前に設定してください。設定では、ここに保存する内容を説明しています。

クローンから実行する

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add notion -e NOTION_TOKENS_DIR="<path to Notion tokens folder>" -- node "$PWD/servers/notion/dist/index.js"

JSON 設定では、コマンドはnodeで、引数はservers/notion/dist/index.jsの完全なパスです。HTTP 経由で複数のクライアント間で 1 つの実行中のコピーを共有する方法については、docs/deploying.mdを参照してください。

HTTP 経由で、接続先ホストを制限するデプロイ環境では、次のように設定します。 MCP_EGRESS_ALLOW=api.notion.com,prod-files-secure.s3.us-west-2.amazonaws.com,s3.us-west-2.amazonaws.com： Notion の API と、ファイルの配信元ホストです。

設定

変数	必須	説明
NOTION_TOKENS_DIR	はい、または CREDENTIALS_DIRECTORY	ワークスペースごとに1つのファイルを格納するフォルダーです。各ファイルは notion-<label> という名前で、そのワークスペースのトークンのみが含まれます。
CREDENTIALS_DIRECTORY		NOTION_TOKENS_DIR が設定されていない場合に読み込まれます。systemd では、LoadCredential=notion-<label>:<path> によって同じファイルがここに配置され、ユニットのみが読み取れます。
NOTION_OUTBOX_DIR	download_files に必要	ダウンロードしたファイルの保存先フォルダーです。サーバーが書き込み、ユーザーが読み取ります。未設定の場合、download_files はこの変数名を示す config エラーを返します。それ以外のツールはすべて動作します。

各ファイルが1つのワークスペースに対応します。notion-personal と notion-work のラベルはそれぞれ personal と work で、サーバーは起動時に 検出したラベルを表示します。ラベルに使えるのは小文字、数字、ハイフンです。空のファイルは スキップされます。既定のフォルダーはないため、テストや手動で実行したコピーが誤って ワークスペースにアクセスすることはありません。ファイルは最大で1分に1回、トークンが 拒否された場合は直ちに再読み込みされるため、新しいトークンを使うために再起動する 必要はありません。すべてのサーバーで共通の変数（トランスポート、制限、アップロード用の MCP_FILE_ROOTS）については、docs/configuration.md を 参照してください。

トークンの取得

ワークスペースごとに、次の手順を行います。

1. そのワークスペースにサインインした状態で https://www.notion.so/profile/integrations を開き、新しい内部インテグレーションを作成します。
2. アシスタントに必要な機能を有効にします。ページとデータベースのコンテンツの読み取り、更新、挿入、およびコメント機能です。ユーザー情報をメールアドレスとともに読み取れる場合にのみ、ユーザーのメールアドレスが表示されます。
3. 内部インテグレーションシークレットをコピーし、トークンフォルダー内の notion-<label> に直接貼り付けます。自分だけが読み取れるように設定してください（モード 0600）。チャットには貼り付けないでください。
4. ページをインテグレーションと共有します。インテグレーションは初期状態では何も表示できません。Notion で、アシスタントがアクセスする必要のある各トップレベルページを開き、••• メニューから「接続」を選択して、インテグレーションを追加します。配下のページにはアクセス権が継承されます。新しいトップレベルページも同じ方法で共有する必要があります。

代わりに、個人用アクセストークンを同じファイルに保存して使うこともできます（そのワークスペースにサインインした状態で https://www.notion.so/developers/tokens から作成し、Notion API の機能を有効にします）。ユーザー本人として動作し、共有設定なしでユーザーが表示できるすべてのページを参照できます。また、インテグレーションでは作成できない非公開のトップレベルページも作成できます。有効期限は1年以内です。

初回実行

アシスタントに Notion の health チェックを実行するよう依頼します。ワークスペースごとに、トークンが受け付けられたか、ワークスペース名とインテグレーション名、インテグレーションがすでにページを参照できるかどうかを表示します。参照できるページがない場合は、上記の手順4を行ってください。

シェルから node dist/index.js --health を実行すると、ワークスペースごとに NOTION: 行が1つ表示され、すべて正常なら終了コード 0、対応が必要な場合（トークンの拒否、機能の不足）は 1、警告の場合（インテグレーションがまだ何も参照できない、または Notion に問題がある）は 2 で終了します。タイマーでの実行に適しています。

ツール

read は変更を加えません。write はワークスペースに変更を加えます。ID を受け取るツールは Notion の URL も受け取り、ワークスペースを自動的に特定します。

ワークスペースと検索

ツール	アクセス	内容
list_accounts	読み取り	トークンファイルがあるワークスペースをラベル別に一覧表示します。Notion へのリクエストは行いません。
health	読み取り	ワークスペースごとに、トークンが受け付けられたか、ワークスペース名とインテグレーション名、インテグレーションがすでにページを参照できるかどうかを表示します。
list_users	読み取り	すべてのワークスペースのユーザー（およびボット）を一覧表示します。ID、名前、トークンで読み取りが許可されている場合はメールアドレスを表示し、単語で絞り込めます。
search	読み取り	すべてのワークスペースを一度に検索し、タイトルでページとデータベースを表示します。各結果にはワークスペースが付記されます。

ページ

ツール	アクセス	機能
read_page	読み取り	ページのプロパティをプレーンな値で、本文をNotionのMarkdownで返します。
read_blocks	読み取り	ページまたはブロックに直接含まれるブロックのID、タイプ、プレーンテキストを返します。議事録ブロックでは、要約、メモ、文字起こしを含むブロックの名前も示します。
create_page	書き込み	データベースの行（列に照らして検証され、またはテンプレートを基に作成）または子ページを作成します。どちらもMarkdown本文を指定できます。
update_page	書き込み	ページのプロパティとアイコンを更新します。
append_content	書き込み	Markdownを末尾、先頭、または指定した箇所の後に追加します。
edit_content	書き込み	ページのMarkdown内で検索して置換します。
replace_content	書き込み	ページの本文全体を置き換えます。本文が空の場合は、clearを指定したときのみ置き換えられます。置き換え前後のページタイトルとブロック数を返します。
move_page	書き込み	同じワークスペース内の別のページの配下、またはデータベースに移動します。
trash_page / restore_page	書き込み	Notionのゴミ箱（30日間保持）への移動と、ゴミ箱からの復元を行います。データベースのテンプレートの場合は、allow_templateを指定したときのみ操作できます。

データベース

ツール	アクセス	機能
describe_database	読み取り	データベースのテーブルと列の情報を返します。タイプ、オプション、ステータスグループ、関連先、数式が含まれます。
query_database	読み取り	where（スキーマに基づく型指定）またはNotion独自のフィルターで絞り込んだ行を返します。並べ替えに対応し、1回の呼び出しで最大1,000行を取得できます。
count_rows	読み取り	条件に一致する行数と、列の値ごとの件数（「ステータスごとのタスク数」など）を返します。行自体は送信しません。
list_views	読み取り	データベースの保存済みビューについて、ID、名前、タイプ、各ビューに保存されたフィルターと並べ替え、列名を返します。
query_view	読み取り	保存済みビューに表示される行を、ビューの合計件数とともに返します。Notionが適用するフィルターをそのまま適用し、ビューの順序で返します。
list_database_templates	読み取り	データベースのページテンプレートについて、ページID、名前、デフォルトかどうかを返します。
add_column	書き込み	データベースに列を追加します。自由な名前、タイプ、設定（オプション、数値形式、数式、関連）を指定でき、追加前にテーブルとの整合性を検証します。
add_options	書き込み	セレクト、マルチセレクト、またはステータス列にオプションを追加します。既存のオプションはIDで保持され、追加後に列を再取得します。
create_database	書き込み	ページの下にデータベースを作成します。タイトル列とその他の列は、作成前に相互の整合性を検証します。

コメントとファイル

ツール	アクセス	機能
get_comments	読み取り	ページの未解決コメントを返します。
add_comment	書き込み	ページへのコメント、またはディスカッションへの返信を追加します。
upload_file	書き込み	パスで指定したファイルをアップロードし、行のファイル列、またはページ本文の末尾にあるブロックに保存します。ファイルサイズとSHA-256を返します。
download_files	読み取り	ページにホストされているNotionのファイル（ファイル列と本文のファイルブロック）をoutboxに保存し、それぞれのSHA-256を返します。

test/tools.snapshot.jsonはクライアントが一覧表示する内容を固定します。このファイルに差分がある場合は、破壊的変更です。

トラブルシューティング

health に「the integration sees no page yet」と表示される場合、または呼び出しが not_shared を返す場合。 Notion は、存在しない ID とインテグレーションに共有されていないページに対して、同じ 404 を返します。ID を確認してから、ページを共有してください（トークンの取得のステップ 4）。トップレベルページを共有すると、その配下のすべてのページも共有されます。

auth。 トークンが拒否されました。失効しているか、パーソナルアクセストークンの有効期限が切れています。新しいトークンを notion-<label> ファイルに入れてください。次の呼び出しで読み込まれます。

forbidden。 インテグレーションに、この呼び出しに必要な機能がありません。https://www.notion.so/profile/integrations で有効にしてください（トークンの取得のステップ 2）。

config。 NOTION_TOKENS_DIR の指定先にトークンファイルがない、読み取れないファイルがある、または 1 つのファイルに複数のトークンが含まれています。download_files では、NOTION_OUTBOX_DIR を設定してください。

親ページを指定していない create_page の input。 Notion は、インテグレーションによるトップレベルページの作成を拒否します。親ページを指定するか、パーソナルアクセストークンを使用してください。それ以外の input は修正すべき内容を示しており、変更は行われていません。

outcome_unknown。 追記、検索と置換、新しいページ、またはコメントの応答が失われました。確認せずに再送信することはありません。再度書き込む前にページを読み取るか、新しいページの場合は search を実行してください。変更がすでに反映されている可能性があります。

conflict：その時点で誰かが同じオブジェクトを編集しました。再度読み取ってから、再試行してください。rate_limited：再試行後も Notion によるスロットリングが続いています（Free プランでは 1 分あたり 180 リクエスト）。1 分待ってください。api：Notion に接続できなかったか、エラーが発生しました。後でもう一度試してください。reason: "drift" の場合、応答の形式が変わっています。報告してください。

仕組み

ID から対応するワークスペースを特定

ID は 1 つのワークスペースにのみ属するため、src/app/locate.ts は各ワークスペースに問い合わせ、応答があるまで続けます。すべてから 404 が返された場合は not_shared です。見つかった ID や、検索またはクエリで明らかになった ID はプロセスの実行中に記憶されるため、見つからない場合の確認は 1 回で済みます。URL は notion.so、notion.site、app.notion.com のいずれかにあり、?p= はデータベース上で開かれたページを示します。

データベースは、それ自体の ID またはデータソースの ID で指定します（検索では両方が返されます）。API 2025-09-03 以降、データベースはデータソースを保持し、通常は 1 つです。複数ある場合は、source でテーブルを指定します。省略すると、それらの名前を示して拒否されます。

エージェントが認識する値

Notion の型	出力	入力
title、rich_text	文字列	文字列。2000 文字（Notion の上限）ごとのまとまりに分割されますが、文字の途中で分割されることはありません
number	Notion が送信した JSON の数値	有限の数値
select、status	オプション名	大文字と小文字を区別せず照合した、既存のオプション。新しい select オプションは allow_new_options の場合のみ指定可能。新しい status は指定不可（API では作成できません）
multi_select	名前	名前。同じルールが適用されます
date	{start, end?, timeZone?}	YYYY-MM-DD、ISO 日時、または {start, end, time_zone}
checkbox	真偽値	真偽値
url、email、phone_number	文字列	文字列。空にするとクリアされます
relation	すべてのページ ID	ページ ID または URL。最大 100 件
files	[{name, url, expiresAt?}]	外部 URL。独自のファイルは upload_file でアップロードします
people、created_by、last_edited_by	{id, name}。ページから ID のみが提供された場合は、ワークスペースのユーザーから名前を取得します	拒否されます
formula、rollup、作成／編集日時、unique_id（PREFIX-12）	計算された値	拒否されます。Notion が計算します
button	値がないため省略	拒否されます

空の値はページまたは行から省略されます（describe_database はすべての列を一覧表示します）。ページオブジェクトに表示される relation のページは最大 25 件です。read_page はプロパティエンドポイントから残りを読み取り（最大 1,000 件）、クエリの行では、そのような列を truncated の下に一覧表示します。サーバーは数値の算術演算を行いません。

where

Notion のフィルターでは、条件のキーを列の型で指定するため、エージェントが間違えやすくなっています。 where では列名、演算子、値を指定し、型はスキーマから取得します。

{"where": [{"property": "Status", "op": "equals", "value": ["In progress", "Blocked"]},
           {"property": "Due", "op": "next_week"}],
 "match": "all"}

型にない演算子や、存在しない選択肢を指定すると、リクエストを送信する前に、利用可能なものとともに拒否されます。人物列には、名前、メールアドレス、ユーザー ID、または "me" を指定できます。名前はワークスペースのユーザーと照合され、まず完全一致で検索し、次に一人の名前の一部として照合されます。複数の人に一致する名前や、誰にも一致しない名前を指定すると、該当する候補とともに拒否されます。where で指定できない条件には、Notion 独自のフィルターオブジェクトを受け取る notion_filter を使用します。指定したフィルターは AND で結合されます。

テンプレート

検索結果ではテンプレートも通常のページとして返されます。また、テンプレートは今後作成されるすべての行の形式を決めるため、list_database_templates でテンプレートを確認でき、trash_page は allow_template が指定されていない場合、テンプレートの削除を拒否します。template を指定した create_page は、そのテンプレートが対象のデータベースに属しているかを確認します。Notion は行の作成直後に内容を反映するため、少し待ってから read_page を実行すると結果を確認できます。テンプレートと一緒に指定したプロパティは保持されます。テンプレートとの競合が起きるため、Markdown の本文は指定できません。

データベースの列を変更する

add_column、add_options、create_database は、リクエストを送信する前に、現在のテーブルに照らしてリクエストを検証します。すでに使われている名前、すでに存在する選択肢、その型では使えない設定、式が指定されていない数式、対象が指定されていないリレーション、Notion の上限である 100 個を超える選択肢などが対象です。Notion のドキュメントでは、スキーマ更新時の選択肢リストは設定する選択肢として扱われています。そのため、add_options は現在のすべての選択肢を ID 付きで送り返してから新しい選択肢を追加し、列を読み戻します。選択肢が失われていた場合、この呼び出しは失敗します。

ファイル

upload_file では、MCP_FILE_ROOTS 内のパスでファイルを指定するか、スクリプトから SHA-256 とともに Base64 形式で渡します。モデルがテキストとして入力する方法は使えません。行のファイル列に追加する場合は、そこにあるファイルに結合されます。それ以外の場合は、本文の末尾に、その種類に応じたブロック（画像、PDF、動画、音声）として追加されます。Notion API はファイル列全体を置き換え、Notion がホストするファイルを書き戻すことはできません。そのため、Notion がホストするファイルを含む列には replace: true が必要です。この指定により、該当ファイルは削除されます。外部リンクは常に保持されます。

download_files は、ページにある Notion ホストのファイルを NOTION_OUTBOX_DIR に保存します。対象にはファイル列と、本文内のファイル、画像、PDF、動画、音声の各ブロックが含まれ、入れ子になったものも対象です（最初の 1,000 ブロックまで）。Notion のリンクは署名付き URL で、1 時間有効です。ワークスペースのトークンを使わず、リダイレクトにも従わずに HTTPS 経由で取得されます。外部リンクはどこにでもつながる可能性があるため、一覧に表示されるだけで、取得はされません。

保存済みビュー

query_view は、クイックフィルターや me も含め、Notion と同じ方法でビューを実行します。Notion はページ ID のみを返し、その結果を約 15 分間保持します。そのため、query_view は各行を自ら読み込みます（デフォルトは 25 行、1 回につき最大 100 行）。nextCursor を使うと、同じ結果の続きを読み込めます。結果の有効期限が切れると、ツールは最初からやり直すよう案内します。その間に行がゴミ箱に移動されたり、共有が解除されたりしていた場合は、unreadable に表示されます。

人物と会議メモ

AI 会議メモのページで include_transcript を指定して read_page を実行すると、要約、メモ、文字起こしが一つの Markdown テキストとして返されます。read_blocks を実行すると、それらの元となるブロックを確認できます。また、transcriptBlockId を指定すると、文字起こしを 1 行ずつ読み込めます。各行にはブロック ID が付いており、AI 要約の引用先から参照できます。

本文全体を置き換える

replace_content は API 経由で元に戻せません。また、モデルは引数を 2 種類間違えることがあります。別の行のページ ID を指定することと、空になった markdown を渡すことです。そのため、本文を空にするには clear: true が必要です。また、応答にはページのタイトルと blocksBefore、blocksAfter が含まれるため、対象ページの間違いや、本文がほとんどなくなったことをすぐに確認できます。

ネットワーク

• バージョン：すべてのリクエストで 2026-03-11 を指定します。Markdown エンドポイントと in_trash が含まれるバージョンです。
• リクエスト頻度：Free プランでは、インテグレーションは固定の1分間に180件のリクエストを送信できます。ワークスペースごとのトークンバケット（同時に30件、その後は毎秒2.5件）を使い、プロセスが処理するすべてのセッションで共有することで、1分間のリクエスト数を180件以下に保ちます。ワークスペース全体の上限については、429 のバックオフと Retry-After に任せます。
• 再送される内容：429 または 409 conflict_error は何も実行されなかったことを示すため、すべてのリクエストを再送します。5xx または接続切断では、実行されたかどうかはどちらとも判断できません。読み取りは再試行し、同じ結果が二度適用されても問題のない処理（プロパティの更新、移動、本文全体の置き換え）も再試行します。それ以外は outcome_unknown として失敗します（どちらに該当するかは notionApi.ts に記載されています）。401 は、トークンファイルを再度読み込んだ後に1回だけ再試行します。
• キャッシュ：データソースの列は1分間、ワークスペースのユーザーは5分間キャッシュします。

ホスト型 MCP ではなく REST を使う理由

Notion のトークンは、ホスト型 MCP のものも含め、すべて1つのワークスペースにスコープされるため、1回のサインインで複数のワークスペースにアクセスすることはできません。ホスト型 MCP のデータソースクエリはプランに依存し、このリポジトリでモデル化されていないツールも中継します。また、そのリフレッシュトークンは失効して、ユーザーの対応が必要になることがあります。パーソナルアクセストークンも、年に一度の更新時には REST 経由でユーザーとして動作します。

scripts/smoke.ts は、ビルド済みサーバーを読み取り専用で実行するか、--write を指定して1ページを書き込み、ゴミ箱に移動します。

制限事項

• 列は追加のみで、名前の変更や削除はできません。ロールアップ、一意の ID、ボタンは Notion アプリで作成します。ユーザー列には書き込めません。
• 会議の文字起こしには、誰がいつ話したかは記載されません。 API はプレーンテキストの paragraph ブロックとして返します（API 2026-03-11、話者フィールドの型がない @notionhq/client 5.27.0）。一方、Notion アプリでは話者の切り替わりとタイムスタンプが表示されます。
• ページを移動できるのは同じワークスペース内だけです。Notion ではワークスペース間でページを移動できません。
• query_database で1回に取得できるのは最大1,000行です（その後は nextCursor を使用します）。count_rows で読み取れるのは、クエリごとに Notion の上限である10,000件までです。
• アップロードは単一パートで、ファイルごとに最大20 MiBです。ダウンロードは50 MiBで停止します。
• ファイル列にある Notion ホストのファイルは書き戻せません。そのため、このような列に追加するには replace: true を指定するか、ファイルを本文に追加します。

Notion 用のその他のサーバー

2026-10-15 に調査。Notion の MCP ページは2026-10-18に再確認しました。

• Notion のホスト型サーバー（mcp.notion.com、Streamable HTTP）では、ブラウザーでの OAuth サインインが必要で、1つの接続につき1つのワークスペースにアクセスします。ブラウザーを使わずにサインインできるのは、ID プロバイダーを利用する Enterprise ワークスペースのみです。ツールセットは最も幅広く、ビュー、ファイルのアップロード、データソースに対する SQL、Custom Agent セッションに対応しています。AI 検索とデータソースに対する無制限の SQL には、Notion AI が有効な Business または Enterprise プランが必要です。保存済みビューへのクエリは、すべてのプランで利用できます。
• @notionhq/notion-mcp-server（Notion のオープンソースサーバー。stdio または HTTP、環境変数にトークンを1つ指定）は、現在積極的にはメンテナンスされていません。
• npm の notion-mcp-server は、コミュニティ製サーバーの中で最も高機能です。トークン1つで stdio または HTTP を利用でき、47種類の操作に対応する3つのツール、データベースのスキーマに照らして検証される型付きフィルターと書き込み、テンプレート、ビュー、ファイルのアップロード、一括書き込みを備えています。
• @suekou/mcp-notion-server（stdio、トークン1つ）も、スキーマから行をクエリして作成できます。
• 見つかった唯一のマルチワークスペースサーバーである notion-multi-workspace は、アーカイブされています。

このサーバーは、1つのヘッドレスサーバーの背後に複数のワークスペースを置き、それぞれに独自のトークンファイルを持たせる用途のためにあります。検索はすべてのワークスペースを一度に対象とし、ページ ID、データベース ID、URL から、それぞれのワークスペースを特定します。また、列の値ごとに一致する行数を、行を送信せずに数えられます。さらに、本文全体の置き換えでは、明示的に指定されない限り空の本文を拒否し、置き換え前後のブロック数を返します。