Notion MCP を調べると、npm の @notionhq/notion-mcp-server（週17万ダウンロード）と、https://mcp.notion.com/mcp というホスト型エンドポイントの2つが出てきます。名前がほぼ同じなので混同されがちですが、認証方式もツール構成も別物で、しかも公式は前者を「もはや積極的にメンテナンスしていない」と明言しています。本記事では両方を実際に叩き、ローカル版のツール定義が21,831トークンを占めること、READMEのツール数が実物と食い違うことまでを実測で確かめます。

Notion MCPの2系統を比較した図。ローカル版notion-mcp-serverはBearerトークン認証で24ツール・21,831トークン、ホスト版mcp.notion.comはOAuth認証で23ツール、公式はホスト版を推奨していることを示す。
「Notion MCP」という名前で流通している2つの実体。認証・ツール命名・メンテナンス状況のすべてが異なる。

30秒でわかる Notion MCP

・同名の2製品がある。ホスト版 mcp.notion.com/mcp（OAuth・公式推奨）と、ローカル版 @notionhq/notion-mcp-server（Bearerトークン・公式が実質終了を宣言）
・ローカル版 v2.5.1 の実測は24ツール・81,951バイト・21,831トークン。ツールを1つも呼ばなくても毎セッション消費される固定費
・READMEの「22ツール」は実物と合わない。v2.0.0 を実際に入れて数えると21個で、retrieve-a-database は v2.5.1 まで存在しなかった
・トークン未設定でもツール一覧は全部返る（fail-open）。実行だけが401で止まる（fail-closed）
・迷ったらホスト版。ローカル版はOAuthを通せないCI・常駐用途の逃げ道

MCPサーバーそのものの仕組みや自作方法は、MCPサーバーの作り方2026年完全ガイド：TypeScript・Python両対応チュートリアルにまとめてあります。本記事は「既にあるNotion公式サーバーを繋ぐ側」の話に絞ります。

Notion MCPとは——ホスト版とローカル版が同じ名前で併存している

MCP（Model Context Protocol）は、AIクライアントと外部データソースを繋ぐための共通プロトコルです。Notion MCP サーバーはその実装のひとつで、MCP 連携の入口として最も需要の大きいもののひとつです。Notion MCPはその実装で、Claude Code や Claude Desktop などのMCPクライアントから、Notionのページ検索・読み取り・作成・更新を行えるようにします。

問題は、「Notion MCP」という呼び名が2つの別物を指していることです。

ローカル版（オープンソース版） は makenotion/notion-mcp-server リポジトリで公開され、npm の @notionhq/notion-mcp-server として配布されています。実測時点の最新は v2.5.1（2026-07-25公開）、GitHub の star は 4,607、fork 625、ライセンスは MIT、オープンIssue は 187件 です。自分のマシンで Node プロセスとして動かし、Notion のインテグレーショントークン（Bearer）で認証します。

ホスト版 は https://mcp.notion.com/mcp で提供される Notion 自身が運用するサーバーです。OAuth で認証し、こちら側に何もインストールしません。

そして公式ドキュメントは、両者の関係についてこう書いています。

The open-source server (notion-mcp-server) is no longer actively maintained. — Notion Developers — Get started with MCP

リポジトリのREADME冒頭にも、同趣旨の警告が置かれています。「Notion MCP（リモート）のみを優先的にサポートしている」「このローカルMCPサーバーのリポジトリは将来的に廃止する可能性がある」「ここのIssueとPull Requestは積極的には監視していない」の3点です。オープンIssueが187件積み上がっているのは、この運用方針と整合しています。

つまり検索で最初に出てくるnpmパッケージは、公式が推していない方です。日本語の解説記事の多くはローカル版の claude_desktop_config.json を書き換える手順を紹介していますが、その前提が現在は変わっています。

Notion MCPのホスト版とローカル版の選択フロー図。OAuthブラウザ認証が通せる環境ならホスト版、CIやサーバー常駐でBearerトークンが必要ならローカル版を選ぶ判断基準を示す。
どちらを選ぶかは「OAuthのブラウザ認証を通せる環境か」でほぼ決まる。

Notion MCP のインストールと接続手順

ホスト版（推奨）

ホスト版はエンドポイントURLを登録するだけで、パッケージのインストールは不要です。Claude Code なら次のコマンドで追加できます。

claude mcp add --transport http notion https://mcp.notion.com/mcp

初回接続時にブラウザが開き、Notion の OAuth 同意画面でワークスペースと共有範囲を選びます。このとき「どのページをAIに見せるか」を選ぶのはユーザー側で、選ばれていないページにはサーバー側からも到達できません。

エンドポイントが生きているかは、認証前でも確認できます。

curl -i -X POST https://mcp.notion.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'

実測（2026-08-27）では HTTP 401 が返り、レスポンスヘッダに次の OAuth チャレンジが含まれていました。

www-authenticate: Bearer realm="OAuth",
  resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp",
  error="invalid_token", error_description="Missing or invalid access token"

resource_metadata を辿ると {"resource":"https://mcp.notion.com/mcp","authorization_servers":["https://mcp.notion.com"],"scopes_supported":["default"],"resource_name":"Notion MCP (Beta)"} が返ります。公式のリソース名は「Notion MCP (Beta)」 で、実測時点ではまだベータ扱いです。認証情報を持たないアクセスがきちんと401で止まる（fail-closed）ことも、この応答から確認できます。

ローカル版

ローカル版は npm から入れます。Notion 側で内部インテグレーションを作成し、対象ページに接続を追加したうえで、発行されたトークンを環境変数で渡します。

npm install @notionhq/[email protected]
NOTION_TOKEN="ntn_xxxxx" \
  node node_modules/@notionhq/notion-mcp-server/bin/cli.mjs

インストール実測では、依存を含めて node_modules が 45MB になりました。依存は axios / express / zod / openapi-client-axios / @modelcontextprotocol/sdk などで、OpenAPI 定義から動的にツールを生成する構成です。

接続がうまくいかないときに切り分けるべき点が3つあります。

・ページがインテグレーションに共有されていない。 トークンが正しくても、Notion側で対象ページに接続を追加していないと API-post-search は空配列を返します。エラーにならないため「動いていない」ように見えず、最も気づきにくい失敗です
・トークンの種類が違う。 Notion のトークンには内部インテグレーション用（ntn_ で始まる）とOAuth用があり、ローカル版が受け取るのは前者です
・データソース移行の影響。 後述のとおり v2.0.0 で database_id が data_source_id に変わっており、古い手順のままだとパラメータ名で弾かれます

注意点が1つあります。 v2.0.0 で Notion API 2025-09-03 に移行し、データベース操作の抽象が「データベース」から「データソース」へ変わりました。post-database-query は query-data-source に置き換わり、パラメータも database_id から data_source_id になっています。古い記事のコード例をそのまま貼ると動きません。

【実測】ツール定義だけで21,831トークン——MCP連携の常駐コストを測る

MCPサーバーを繋ぐと、ツールを1つも呼ばなくてもその定義がコンテキストに載ります。これは毎セッション発生する固定費なので、実際に測りました。

計測方法は、stdio でサーバーを起動して initialize → tools/list を投げ、返ってきた JSON をそのまま数えるというものです。

# initialize と tools/list を stdio に流し込んでレスポンスを取得する
node node_modules/@notionhq/notion-mcp-server/bin/cli.mjs

結果（2026-08-27・cl100k_base 換算）:

バージョン ツール数 tools/list のバイト数 トークン数
v2.0.0 21 67,469 18,122
v2.5.1（最新） 24 81,951 21,831

21,831トークンは、目安として日本語の記事なら2〜3本ぶんに相当する分量です。Notion MCP を1つ繋いだだけでこれが毎回載ります。

内訳を見ると、ツールの説明文（description）の合計はわずか1,855バイトしかありません。残りはすべて入力パラメータの JSON Schema です。ローカル版は Notion の OpenAPI 定義から機械的にツールを生成しているため、REST API のリクエストボディの構造がそのまま schema として展開されます。これが肥大の主因です。

トークンの重い順に並べると、上位はページ・データソースの書き込み系に集中します。

ツール トークン数
API-update-page-markdown 1,572
API-post-search 1,307
API-patch-page 1,100
API-post-page 1,013
API-query-data-source 971
（最軽量）API-get-self 749

この偏りには理由があります。API-update-page-markdown と API-post-search は、Notionのブロック構造やフィルタ条件を表現するために深くネストしたオブジェクトを引数に取ります。JSON Schema はネストの深さに比例して膨らむため、「機能が多いツール」ではなく「引数の構造が複雑なツール」が重くなります。

最軽量のツールでも749トークンあり、24個すべてが700トークン超という平坦な分布です。「使わないツールだけ軽い」という構造にはなっていないので、必要なツールだけ残す絞り込みが効きます。ローカル版は環境変数でツールを制限でき、ホスト版は Notion 側の設定で共有範囲を絞れます。

なお ホスト版のツール定義が実際に何トークンかは、本記事では未検証です。 OAuth 認証を通さないと tools/list に到達できず、認証には実ワークスペースの同意操作が要るためです。公式は「AIエージェント向けに設計され、トークン消費を最適化した」と説明していますが、その数値は確認していません。

MCPサーバーのツール数と常駐コストの関係は、x64dbg-MCP Serverとは｜AIにデバッガを操作させるZig製MCPプラグイン71ツール実測でも71ツールという別のスケールで測っています。あわせて読むと、ツール数がそのままコストに直結するわけではないことが分かります。

【実測】READMEの「22ツール」は実物と合わない

README の v2.0.0 の節には、はっきりこう書かれています。

Total tools now: 22 (was 19 in v1.x)

これを検証するため、v2.0.0 を名指しでインストールして数えました。

npm install @notionhq/[email protected]

結果は 21個 でした。1個足りません。

v2.5.1 との差分を取ると、v2.5.1 で増えた3つが分かります。

v2.5.1 で追加されたツール
API-retrieve-a-database
API-retrieve-page-markdown
API-update-page-markdown

問題は API-retrieve-a-database です。READMEは v2.0.0 の「New tools (7)」の一覧にこれを含め、さらに本文で「retrieve-a-database は引き続き利用可能」と書いています。ところが実際の v2.0.0 の配布物には存在せず、v2.5.1 で初めて現れます。READMEの「22」は、この存在しなかった1個を数えた結果と整合します。

削除されたツールは0個だったので、READMEの「removed 3 / new 7」という説明自体は方向としては正しく、数え方だけがずれている形です。

この種のドリフトは珍しくありませんが、MCPサーバーのツール数はコンテキスト消費に直結するので、見積もりにREADMEの数値を使うと外れます。実物を tools/list で数えるのが確実です。

認証なしで何が起きるか——一覧はfail-open、実行はfail-closed

ローカル版を NOTION_TOKEN を一切設定せずに 起動したところ、次の挙動になりました。

initialize は成功します。serverInfo は {"name":"Notion API","version":"1.0.0"} を返しました。

tools/list も成功し、24個すべてのツール定義が返ってきました。認証情報が無いことは一覧取得を妨げません。

tools/call は失敗します。最も無害な API-get-self（自分自身の情報取得）を呼ぶと、Notion API から次が返りました。

{"status":401,"object":"error","code":"unauthorized","message":"API token is invalid."}

まとめると 「一覧は fail-open、実行は fail-closed」 です。データが漏れるわけではないので実害はありませんが、2点の実務的な含意があります。

・設定ミスに気づきにくい。 トークンを渡し忘れてもクライアント側ではツールが正常に見えるため、実際に呼ぶまで壊れていることが分からない
・トークン未設定でもコンテキスト消費は発生する。 21,831トークンは認証の成否と無関係に載る。動いていないMCPサーバーを繋ぎっぱなしにしていると、コストだけ払い続ける

この挙動を1本の流れで見ると、どこで止まりどこで止まらないのかがはっきりします。

sequenceDiagram participant C as "MCPクライアント" participant S as "notion-mcp-server
（トークン未設定）" participant N as "Notion API" C->>S: "initialize" S-->>C: "成功 serverInfo: Notion API 1.0.0" C->>S: "tools/list" S-->>C: "成功 24ツール・21,831トークン" Note over C,S: "ここまで認証は一切問われない（fail-open）" C->>S: "tools/call API-get-self" S->>N: "GET /v1/users/me" N-->>S: "401 unauthorized" S-->>C: "result の中に401のJSON文字列" Note over S,N: "実データに触る段で初めて止まる（fail-closed）"

なお tools/call のエラーは MCP プロトコルレベルの error ではなく、result の中に Notion API のエラーJSONが文字列として入る形で返ります。エラーハンドリングを書くときは、result の中身まで見ないと失敗を検出できません。

ホスト版とローカル版、どちらを選ぶか

実測とドキュメントから整理すると、次のようになります。

観点 ホスト版 mcp.notion.com/mcp ローカル版 notion-mcp-server
認証 OAuth（ブラウザ同意） Bearer トークン（環境変数）
インストール 不要 npm・node_modules 45MB
ツール数 23（公式ドキュメント掲載数） 24（実測）
ツール命名 notion-search 等・エージェント向け設計 API-post-search 等・REST APIの写し
トークン消費 「最適化済み」と公式説明（数値は未検証） 21,831トークン（実測）
メンテナンス 公式が積極サポート 「もはや積極的にメンテナンスしていない」
提供状態 Beta（resource_name より） v2.5.1・安定版
向く用途 対話的な利用全般 OAuthを通せないCI・サーバー常駐

ホスト版のツール名を見ると、設計思想の違いがはっきりします。notion-fetch / notion-search / notion-create-pages のようにやりたいこと単位でまとまっており、notion-convert-page-to-skill のようにローカル版に対応物がないものもあります。一方ローカル版は REST API のエンドポイント1つがツール1つなので、AIから見ると「どれを使えばいいか」の判断が難しくなります。

選び方は単純です。 OAuth のブラウザ認証を通せる環境ならホスト版。通せない（CI、ヘッドレスサーバー、共有アカウント運用など）ならローカル版、ただし公式サポートが薄いことを承知のうえで。

ひとつ注意すべき点として、ホスト版の notion-search はNotion AI プランがないとワークスペース内検索に限定されると公式ドキュメントに明記されています。Slack や Google Drive を横断する検索は、MCPの機能ではなく Notion AI の機能です。「Notion MCP を入れれば社内の情報源を全部横断できる」と読むと、プラン要件を見落とします。

もう1点、ローカル版を選ぶ理由が「無料だから」ではないことも押さえておく価値があります。どちらもNotionのプラン内で使えるもので、MCPサーバー自体に課金はありません。ローカル版の存在理由は認証方式であって、コストではありません。

移行のコストは小さいという点も実務上は重要です。MCPのツールはサーバー起動時にクライアントが自動で再取得するため、接続先を切り替えればツール一覧はその場で入れ替わります。設定ファイルに書いたエンドポイントを差し替えるだけで済み、コード側の書き換えは発生しません。ただしプロンプトやスキルにツール名をハードコードしている場合は別で、API-post-search と notion-search は名前が全く違うため、そこだけは書き換えが要ります。

MCP連携を実務で使うときの前提

Notion MCP に限らず、MCPサーバーを業務で繋ぐときに効いてくる観点を整理しておきます。

接続するサーバーの数だけ固定費が乗ります。 Notion MCP 単体で21,831トークン、デバッガ系だと71ツール規模になることもあります。3つ4つと繋ぐと、作業を始める前にコンテキストの相当量が埋まります。常時接続するものと、必要なときだけ有効化するものを分けるのが現実的です。

権限の粒度はMCPサーバー側でなくSaaS側で決まります。 Notion の場合、ホスト版はOAuth同意画面で、ローカル版はインテグレーションの「接続」設定でページ単位の共有範囲が決まります。MCPクライアント側にはこの制御がないので、繋ぐ前にNotion側で範囲を絞るのが正しい順序です。

同じ計測方法で他のMCPサーバーも測っています。 Blender MCPとは｜25ツール6,480トークンとテレメトリ既定ONを実測で確かめるは25ツールで6,480トークン、Backlog MCPとは｜62ツール11,710トークンとENABLE_TOOLSETSでの半減を実測は62ツールで11,710トークンでした。本記事の Notion MCP ローカル版（24ツール・21,831トークン）が3つの中で最も重いという結果です。ツール数ではなく引数スキーマの複雑さがコストを決めることが、3サーバーの実測で確認できます。

まとめ

Notion MCP サーバーは、同じ名前で2つの実体が併存しているのが最大のつまずきポイントです。MCP 連携を業務に入れる前に、どちらの話をしているのかを確定させてください。

・検索で出てくる npm パッケージ（週17万DL）は、公式が「もはや積極的にメンテナンスしていない」と書いている方
・新規に始めるならホスト版 https://mcp.notion.com/mcp。実測時点では Beta 表記
・ローカル版 v2.5.1 の実測値は 24ツール・81,951バイト・21,831トークン。バージョンが上がるほど増えている（v2.0.0 は21ツール・18,122トークン）
・READMEのツール数は実物と合わない。v2.0.0 は README の「22」に対して実測21個で、retrieve-a-database は v2.5.1 まで存在しなかった
・トークン未設定でもツール一覧は全部見える（実行だけ401で止まる）。設定ミスに気づきにくい

数値をREADMEから引き写すのではなく、tools/list を1回叩いて数える——それだけで、見積もりのずれとバージョン間の差分は自分で確認できます。

参照ソース