Notion MCP Server

Notion MCP Server — Claude、Cursor、VS Code、CodexをNotionに接続

notion-mcp-serverは、Claude Code、Claude Desktop、Cursor、VS Code、Codex、その他あらゆるMCPクライアントに、1つのトークンでNotionへの読み書きアクセスを提供するModel Context Protocol（MCP）サーバーです。AIは、自然な言葉で検索、ページの作成と編集、データベースへのクエリ、コメントの追加、ファイルのアップロードを行えます。

• 無料プランを含む、すべてのNotionプランでトークン認証に対応。 ブラウザーでのサインインは不要なため、CI、cronジョブ、バックグラウンドエージェント、自社サーバー上など、ヘッドレス環境でも実行できます。
• コンテキストの消費を抑えます。 接続時に必要なトークンは3つのツールで1,005トークンです。Notionのオープンソースサーバーの17,163トークンと比べて少なく、ページ読み取りのデータ量も82％削減できます。ベンチマーク →
• エージェント向けに設計。 アトミックなロールバックと冪等性キーに対応した一括書き込み、レート制限時の再試行、Markdownの入出力、呼び出しを修正する方法をモデルに伝えるエラーを備えています。

クイックスタート

1. Notion トークンを取得します。 app.notion.com/developers/tokens を開き → + New token → 名前を付けて、ワークスペースを選択 → Create token → ntn_… の値をコピーします。パーソナルアクセストークンを使うと、ページごとに共有しなくても、あなた が閲覧できるすべてのものにアクセスできます。作成できない場合は、別のトークンの方法をご覧ください。

2. インストールします。

npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here

add-mcp は、お使いのマシン上にある MCP クライアントを検出し、選択したクライアント用の設定を書き込みます。対応クライアントは、Claude Code、Claude Desktop、Cursor、VS Code、Codex、Gemini CLI、Cline、Windsurf、Zed などです。現在のプロジェクトではなく、ユーザー用にインストールするには -g を追加します。

--env フラグは必ず付けてください。これがないと、トークンなしで設定が書き込まれ、すべての呼び出しが認証エラーで失敗します。

または、ワンクリックでインストールできます。

• Cursor： 生成された設定内の YOUR_NOTION_TOKEN を置き換えます。
• VS Code（Copilot エージェントモード）： トークンの入力を求められ、シークレットとして保存されます。
• Claude Desktop： .mcpb ファイルをダブルクリックするか、Settings → Extensions にドラッグして、トークンを貼り付けます。Node.js は不要です。初めての方は、何も知らなくても進められる手順ごとのガイドをご覧ください。

Claude Code をお使いですか？ 代わりにプラグインとしてインストールしてください。 このプラグインには、Notion のワークフロースキルとサーバーが同梱されています。このスキルは、Claude に検索するタイミング、where を使ってデータベースをフィルタリングする方法、書き込みをまとめて行う方法を教えます。Claude Code はインストール時（または後から /plugin configure notion-mcp-server@awkoy を実行したとき）にトークンの入力を求め、システムのキーチェーンに保存します。

/plugin marketplace add awkoy/notion-mcp-server
/plugin install notion-mcp-server@awkoy

このプラグインは、プラグイン自身のバージョンに一致する npm リリースを実行し、Node.js 22 以降が必要です。デフォルトの親ページと読み取り専用の切り替え機能もあります。詳しくはプラグインの READMEをご覧ください。

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

claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server

[mcp_servers.notion]
command = "npx"
args = ["-y", "notion-mcp-server"]
env = { NOTION_TOKEN = "ntn_paste_your_token_here" }

claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here \
  -- docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest

3. 試してみます。 新しいチャットで、次のように入力します。

「Notion を使って『Hello from my agent』というページを作成し、今日試すことを3つ含むチェックリストを追加してください。」

AI が notion_write を呼び出し、新しいページへのリンクを返します。

質問できること

• 「Tasks データベースで Status が 'Doing' の行をすべて見つけて、期限切れのものを教えてください。」
• 「この50ページの名前を新しい規則に合わせて変更してください。」 50回ではなく、1回のバッチ呼び出しで実行します。
• 「'Weekly review' テンプレートからページを作成して、この要約を記入してください。」
• 「仕様ページを書き直してください。見出しを整えて、コードサンプルを追加してください。」 ページはMarkdownとして往復処理されます。
• 「昨日の会議メモに、1段落の要約をコメントしてください。」
• 「この図をデザインページにアップロードしてください。」
• 「バグ報告のスクリーンショットを見て、何が問題か教えてください。」 モデルは画像そのものを受け取ります。

どのNotion MCPを使うべきですか？

claude.aiやChatGPTでNotionとチャットするには、Notionのホスト型コネクターをワンクリックで利用できます。エージェントを無人で実行する場合、利用プランにMCPトークンが含まれない場合、コンテキストのコストが重要な場合、または自分のホスト上で実行したい場合は、このサーバーをお使いください。詳細な比較 →

設定

トークン：PATまたは内部インテグレーション

どちらも同じNOTION_TOKEN環境変数に設定します。異なるのは取得方法だけです。

• PATを作成できるユーザー。 ワークスペースのオーナーは常に作成できます。FreeおよびBusinessプランではデフォルトでオーナーのみ、Plusではすべてのメンバーが作成できます。また、管理者はBusinessおよびEnterpriseでポリシーを変更できます。ゲストは作成できません。
• 有効期限と取り消し。 作成時に有効期間を指定します。最長で1年間です。同じトークンページで取り消すと、ただちに使用できなくなります。詳細：NotionのPATガイド。
• 閲覧できるページでobject_not_foundが表示される場合。 そのページに接続されていない内部インテグレーションが原因です。ページに接続するか、PATに切り替えてください。

環境変数

HTTP 変数については、リモート / HTTP トランスポートを参照してください。v1 または v2 からアップグレードしますか？環境変数はすべて引き続き使用できます。ツール名が変更されています。詳しくは MIGRATION.md を参照してください。

操作の制限

NOTION_READ_ONLY=true にすると、すべての書き込みが無効になります。より細かく制御するには、NOTION_ALLOWED_OPERATIONS と NOTION_BLOCKED_OPERATIONS に、カンマ区切りの操作名またはプリセット（read、write、destructive（アーカイブ、ゴミ箱への移動、削除）、あるいはファミリー（pages、blocks、databases、data_sources、views、comments、users、files）を指定します。ブロックリストが優先されます。

{ "env": { "NOTION_ALLOWED_OPERATIONS": "read" } }                       // read-only
{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }                // everything except removals
{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }

無効化された操作はツールスキーマから除外されるため、モデルに表示されません。サーバーは起動時に、解決された設定を次のように出力します。例：Operation access: 22/48 enabled (allow=read; block=(none))。

ブロックする代わりに確認を求めるには、NOTION_CONFIRM_DESTRUCTIVE=true を設定します。破壊的操作の実行前に、クライアントに対象の名前を示す「はい／いいえ」のダイアログが表示されます。クライアントは MCP エリシテーションに対応している必要があります。完全なルール、操作ごとの一覧、操作単位での制御の制限については、docs/configuration.mdを参照してください。

ファイル

upload_file は、NOTION_UPLOAD_MAX_BYTES（デフォルトは 1 GiB）までの Base64、公開 URL、またはローカルパスを受け付けます。ソースを選ぶのはモデルのため、サーバーは自身で読み取る 2 種類のソースを保護します。

• ローカルパス。 アップロード元として許可するディレクトリを NOTION_UPLOAD_ROOT に設定してください。このディレクトリの外にあるパスは、シンボリックリンクも含めて拒否されます。設定しない場合、HTTP 経由ではパスを指定できません。また、stdio 経由では、ドットで始まるファイルやディレクトリ（~/.ssh、~/.aws、.env）を経由するパスや、MCP クライアントがトークンを保存するシステムフォルダーまたはアプリデータフォルダー（/proc、/dev、~/Library、%APPDATA%）内のパスは拒否されます。NOTION_UPLOAD_ROOT=/ を設定すると、この制限は解除されます。ルート内では .env や .git も含めてすべてのファイルを読み取れるため、HTTP 経由で使う場合は、サーバーを呼び出せる相手に渡してもよいファイルだけを格納したルートを選んでください。
• URL。 http と https のみ利用できます。リダイレクトを含むすべての経由先がパブリックアドレスに解決される必要があります。そのため、ループバック、プライベートネットワーク、クラウドのメタデータエンドポイントは拒否されます。イントラネットで利用する場合は、NOTION_UPLOAD_ALLOW_PRIVATE_URLS=true を設定するとこの制限を解除できます。取得は NOTION_UPLOAD_URL_TIMEOUT_MS（30 秒）経過後、または本文がサイズ制限を超えた時点で停止します。

Notion の署名付きファイル URL はそれぞれ約 500 トークン分の長さがあり、1 時間以内に期限切れになります。NOTION_FILE_URLS=ref を設定すると、レスポンス内の URL が短い notion-file: 参照に置き換わり、get_file_url と get_image が必要に応じて解決します。参照の仕組み →

リモート／HTTP トランスポート

デフォルトでは、サーバーは stdio で通信します。MCP_TRANSPORT=http を設定すると、Web クライアント、ネットワーク接続されたエージェント、共有デプロイメント向けの Streamable HTTP エンドポイントとして実行できます。

MCP_TRANSPORT=http PORT=3000 NOTION_TOKEN=ntn_xxx npx -y notion-mcp-server
# -> notion-mcp-server vX.Y.Z running on http://127.0.0.1:3000/mcp

⚠️ /mcp にアクセスできる人は誰でも、あなたの NOTION_TOKEN を使って操作できます。 デフォルトのループバックでは、ローカルプロセスのみが対象です。ループバック以外の HOST を指定した場合、MCP_AUTH_TOKEN がないと起動しません。さらに、前段に TLS を設置してください。

HTTP 経由では、呼び出し元がサーバーのマシン上にいるとは限らないため、NOTION_UPLOAD_ROOT を設定しない限り、upload_file にローカルパスを指定できません。Base64 と URL のソースは通常どおり使用できます。ファイルを参照してください。

claude mcp add --transport http notion https://your-host/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Docker、ヘルスチェック、プロトコルのバージョンについては、docs/http-transport.md を参照してください。

ツールと操作

呼び出すことになる 46 種類の操作は、3 つのツールで実行できます。読み取りには notion_read、書き込みには notion_write を使い、notion_describe は操作の JSON Schema と動作する例を返します。すべての ID フィールドには Notion の URL も指定できるので、**「共有 → リンクをコピー」**で取得したものを貼り付けてください。呼び出し例、一括処理オプション、MCP リソースについては、docs/operations.md を参照してください。

ツールごとの権限

読み取りと書き込みが分かれているため、読み取りは一度承認し、書き込みはプロンプトで確認するようにできます。Claude Code の settings.json では（notion はサーバーに付けた任意の名前です）：

{ "permissions": { "allow": ["mcp__notion__notion_read", "mcp__notion__notion_describe"] } }

操作メニュー（46 個の操作と 2 つのエイリアス）

よくある質問

Notion の Free プランでも動作しますか？ はい。どのプランでも、ワークスペースのオーナーがパーソナルアクセストークンを作成でき、サーバーに必要なのはそれだけです。

OAuth を使わない Notion MCP サーバーはありますか？ これがそうです。トークンで認証するため、誰も「認証」をクリックする必要はありません。Notion のホスト型 MCP で OAuth が不要になるのは、ワークスペースのオーナーが MCP トークンを作成する Business プランと Enterprise プランのみです。

どのクライアントで使えますか？ あらゆる MCP クライアントで使えます。Claude Code、Claude Desktop、Cursor、VS Code（Copilot エージェントモード）、Codex、Gemini CLI、Cline、Windsurf、Zed、Continue、および任意の MCP ホストを介したローカルモデルに対応しています。詳しくはよくある質問をご覧ください。

トラブルシューティング

• 毎回の呼び出しで「Notion auth failed」と表示される： トークンが未設定、取り消し済み、または期限切れです。クライアント設定の NOTION_TOKEN を確認し、app.notion.com/developers/tokens でトークンが有効なままか確認してください。--env を指定せずに add-mcp でインストールしましたか？ フラグを付けて再実行してください。
• object_not_found ／「Could not find …」： 内部インテグレーションから見えるのは、接続済みのページのみです。そのページを接続するか、PAT に切り替えてください。
• 「No parent page configured」： 呼び出しで parent を渡すか、NOTION_PAGE_ID を設定してください。
• multi_source_database： データベースに複数のデータソースがあります。list_data_sources を呼び出し、database_id の代わりに data_source_id を渡してください。
• 成功した結果に warnings が含まれる： 呼び出しは実行されています。各項目には、無視されたフィールドまたは修正されたプロパティ名が記載されています。
• Claude Desktop にツールが表示されない： トークンの入力ミス（引用符の内側に記述する必要があります）、または再起動前にアプリを完全に終了していません（Cmd+Q）。
• 起動ログに「Notion auth check failed」と表示されるが、ツールは動作する： 起動時のチェックはベストエフォートです。呼び出しが成功する場合は無視してください。
• Docker がすぐ終了する、または「NOTION_TOKEN is not set」と表示される： -i を追加し、-e NOTION_TOKEN または -e NOTION_TOKEN=ntn_xxx の形式で指定してください。-e NOTION_TOKEN ntn_xxx の形式では指定しないでください。

解決しない場合は、よくある質問を確認するか、GitHub のイシューを作成してください。

プライバシー

サーバーはお使いのマシンまたはご自身のホスト上で実行され、設定したトークンを使って HTTPS 経由で api.notion.com とのみ通信します（HTTPS_PROXY が設定されている場合はプロキシ経由で通信します）。テレメトリや分析機能はなく、通信経路に当社のサーバーが介在することもありません。トークンは MCP クライアントが保存する場所にとどまります。get_image は、Notion がホストするファイルに対して Notion が返す署名付き URL のみを取得します。upload_file は、要求された場合にのみローカルファイルを読み込むか URL から取得し、プライベートアドレスまたはループバックアドレスに解決される URL は拒否します。お客様のデータに関する Notion 独自の取り扱いについては、Notion のプライバシーポリシーをご覧ください。

開発

git clone https://github.com/awkoy/notion-mcp-server.git && cd notion-mcp-server
npm install && npm run build && npm test

アーキテクチャ、クライアントでのローカルビルドの実行方法、実際のワークスペースを使ったエンドツーエンドテストについては、docs/development.mdをご覧ください。PR を歓迎します。PR を作成する前に npm test を実行してください。

License

MIT — see LICENSE.

mcp-name: io.github.awkoy/notion-mcp-server