ビジネス向け大学向けゆめさくエンジニアWomen
ゆめさくコード

Notion MCP

Notion のページ・データベースを操作する MCP サーバー。

Notion にはホスト型のリモートサーバー (mcp.notion.com、OAuth) と、自分でプロセスを立てるオープンソース版 (@notionhq/notion-mcp-server、インテグレーショントークン) があります。後者はトークン無しでも起動・ツール一覧まで進み、API 呼び出し時に 401 で失敗することを確認しました。

対象
@notionhq/notion-mcp-server / https://mcp.notion.com/mcp
確認した版
版: 2.5.1 / hosted (2026-09-17 時点)
確認日
確認日:

この環境で確かめたこと

  • @notionhq/notion-mcp-server@2.5.1 がトークン無しでも起動し、initialize に応答した (serverInfo {"name":"Notion API","version":"1.0.0"})
  • tools/list で 24 個の API ツール (API-post-search, API-retrieve-a-page, API-patch-page 等) が返った — トークン不要
  • NOTION_TOKEN 未設定で API-get-self を呼ぶと 401 unauthorized (Authorization header must use the format "Bearer <token>") がツール結果として返った
  • 不正な ntn_ トークンでは 401 "API token is invalid." が返った
  • ホスト型 https://mcp.notion.com/mcp は未認証で 401 + oauth-protected-resource (scope default、名前 "Notion MCP (Beta)") を返した

確認環境: macOS arm64 / Node 26

クライアント別の対応状況

同じサーバーでもクライアントごとに確認の深さが違います。確かめていないものは「未観測」と出します。

検証項目Claude Code2.1.81Codex CLI0.144.3Cursor未導入VS Code未導入検証クライアントNode 26 / SDK 1.30.0
クライアントへの登録 (OSS 版)codex mcp add の登録経路は Playwright MCP で確認済みの同型。Claude Code は設定形式のみ確認。一部確認確認済み未観測未観測—
initialize / tools/list (トークン無し)トークン無しで 24 ツール取得を確認。AI クライアント越しは未観測。未観測未観測未観測未観測確認済み
API 呼び出し (実データ)トークン無し/不正トークンでは 401 が返ることを確認。有効トークンでの成功は未観測。未観測未観測未観測未観測失敗を確認
ホスト型 (OAuth)401 + protected-resource メタデータを確認。OAuth 完了後の操作は未観測。未観測未観測未観測未観測確認済み
  • 確認済みこの環境で再現確認
  • 一部確認一部だけ確認
  • 未観測この環境では試していない
  • 失敗を確認失敗を再現して確認

クライアント別の設定手順

使っているツールのタブを選んでください。手順を終えたら各ステップのボタンで記録できます。

設定の置き場: ~/.claude.json (mcpServers + env)

設定形式は確認済み。トークンを env に入れる形。

  1. 1

    インテグレーショントークンを用意する

    Notion のインテグレーション設定で内部トークンを発行し、使いたいページ/DB をそのインテグレーションに共有する。トークンは ntn_ または secret_ で始まる。

  2. 2

    サーバーを登録する

    env に NOTION_TOKEN を渡す形で登録する。

    ~/.claude.json

    "mcpServers": {
  "notion": {
    "command": "npx",
    "args": ["-y", "@notionhq/notion-mcp-server@2.5.1"],
    "env": { "NOTION_TOKEN": "ntn_..." }
  }
}

接続テスト: Claude Code での確認

トークン無しでも tools/list には応答するため、接続確認は API-get-self (自分の情報) を呼んで 401 でなくユーザー情報が返るかで見る。401 が返る場合はトークン未設定または無効 (両方とも実測済み)。

ターミナル

# クライアントから「API-get-self を呼んで」と指示したときの応答で判断
# 401 unauthorized → トークン未設定 / "API token is invalid." → トークン誤り (実測)

権限・認証スコープ

OSS 版の認証
内部インテグレーショントークン (ntn_/secret_ 系) を Bearer ヘッダーで渡す。権限は「そのインテグレーションに共有されたページ/DB」のみ。
ホスト型の認証
OAuth Bearer。protected-resource メタデータ上の scope は default、リソース名 "Notion MCP (Beta)" (確認済み)。
失敗の見え方
認証失敗はプロトコルエラーではなくツール結果の content に 401 JSON として返る (実測)。クライアント画面上はツール成功に見えることがあるので中身を読む。

既知の失敗

実際に観測した失敗だけを載せます。再現できていないものは「未観測」と書きます。

  • トークン無しで API 呼び出しが 401 になる

    API-get-self で "Authorization header must use the format \"Bearer <token>\"." がツール結果として返った (isError フラグは立たない)。

    対処: NOTION_TOKEN を設定して再起動する。

  • トークンを入れても 401 が消えない

    存在しない ntn_ トークンでは "API token is invalid."。有効なトークンでも、ページをインテグレーションに共有していないと検索に出ない (この挙動は未観測)。

    対処: Notion 側で対象ページをインテグレーションに共有する。

  • 初回の起動が無反応に見える

    初回 npx 実行でパッケージ取得中は initialize に応答せず、25 秒でタイムアウトした。2 回目以降は即応答 (実測)。

    対処: npx -y @notionhq/notion-mcp-server を一度素で実行してキャッシュする。

隣のガイド

MCP ハブ (サーバー目録) に戻る

最終確認起動・一覧・401 失敗まで確認済み

起動とツール一覧、トークン無し/不正時の 401 応答は実測済み。実データの読み書きとホスト型 OAuth の完了は有効なワークスペースが必要なため未観測。