/setup-notion

description: "Lesson command"
duration: "約10分"
prerequisites: ["Notionアカウントを持っている（無料プランでOK）", "ブラウザが使える", "Node.js 18以上"]
level: "beginner"
tags: ["setup", "notion", "ncli", "mcp", "oauth"]
nonInteractiveMode: incompatible

Notion CLI (ncli) + Hosted MCP セットアップ（OAuth 統一）

Step 0: セットアップ進捗の確認

**AIが自動実行する内容:** 1. `uv run python tools/setup_progress.py show --current setup-notion` を実行して進捗を表示 2. 既存の設定を自動検出:

• `which ncli` で ncli がインストール済みか確認
• Claude Code の場合: `~/.claude/mcp_settings.json` に `notion` サーバーが定義されているか確認
• Cursor の場合: `~/.cursor/mcp.json` に `notion` サーバーが定義されているか確認
• ncli インストール済み＆MCP設定済みの場合、Step 6（接続テスト）のみ実行して完了にできる

このセッションでやること

| 項目 | 内容 | |------|------| | ゴール | ncli（Notion CLI）と Notion 公式の Hosted MCP を **OAuth 認証** で接続し、ターミナル＋MCP 経由で Notion を操作できるようにする | | 所要時間 | 約10分 | | 前提条件 | Notionアカウント（無料プランでOK）、Node.js 18以上、ブラウザ | | 操作レベル | CLIコマンド入力なし（すべてAIが自動実行 + ブラウザでの OAuth 承認のみ） | | 認証方式 | **このセットアップ手順では OAuth のみ**を使います（APIキー不要）。<br>※ 一部のレガシースクリプト（`tools/run_lesson_14_11.py` 等）は引き続き `NOTION_API_KEY` を要求します。詳細は `.env.example` を参照 |

**このセッションの流れ:** 1. ncli（@sakasegawa/ncli）をインストールする（AIが自動実行） 2. `ncli login` を実行してブラウザで Notion OAuth を承認する 3. `ncli whoami` / `ncli search` で動作確認する 4. MCP設定ファイルに Notion Hosted MCP（OAuth）を追加する（AIが自動作成） 5. Claude Code / Cursor を再起動 → 初回利用時に OAuth ダイアログを承認する 6. MCP接続テスト

> **Hosted MCP + OAuth に統一した理由**: 旧方式の Internal Integration Token は、Notion 上でインテグレーションを作成し、各ページに「Add connections」で個別に共有する必要がありました。OAuth ではブラウザでログインするだけで、ワークスペース全体への権限を一度に付与できるため、**この Hosted MCP 手順では**ページ単位の共有設定は **不要** です。なお、`NOTION_API_KEY` を直接読む旧スクリプト（`tools/run_lesson_14_11.py` 等）を実行する場合は、従来通り Internal Integration Token も併用してください。

> **ヒント**: AIの応答が途中で止まった場合は「続きを表示して」「止まってるよ」と入力すると再開します。

---

準備チェック

**AskQuestionの設定:**

{
  "title": "セッション開始前の確認",
  "questions": [{
    "id": "readiness",
    "prompt": "準備はできていますか？",
    "options": [
      {"id": "ready", "label": "準備OK！始めましょう"},
      {"id": "check_prereq", "label": "前提条件を確認したい"},
      {"id": "which_tool", "label": "Claude Code と Cursor のどちらを使っているか確認したい"},
      {"id": "different_lesson", "label": "別のレッスンに移動したい"}
    ]
  }]
}

(ready → Step 1へ) (check_prereq → 「Notionアカウント（無料プランでOK）があり、ブラウザでログインできれば準備OKです。Node.js 18 以上もインストール済みであることを確認してください」と案内) (which_tool → 「Claude Code を使っている場合と Cursor を使っている場合で MCP 設定ファイルの場所が異なります。Step 4 でそれぞれの手順を案内します」と説明) (different_lesson → モジュール一覧を表示)

---

Step 1: ncli（Notion CLI）のインストール

**AIが実行すること:** 1. Node.js のバージョンを確認: `node --version`（18以上が必要） 2. ncli がインストール済みか確認: `which ncli` 3. 未インストールの場合、以下のコマンドを実行:

npm install -g @sakasegawa/ncli

4. インストール後、`ncli --version` で確認する

**AskQuestionの設定:**

{
  "title": "Step 1: ncli のインストール",
  "questions": [{
    "id": "ncli_status",
    "prompt": "ncli のインストールを実行しました。結果を確認してください。",
    "options": [
      {"id": "installed", "label": "インストールできました！"},
      {"id": "npm_error", "label": "npm install でエラーが出た"},
      {"id": "no_node", "label": "Node.js がインストールされていない"},
      {"id": "command_not_found", "label": "ncli コマンドが見つからない"}
    ]
  }]
}

(installed → Step 2へ) (npm_error → `npm cache clean --force` を実行後リトライ。権限エラーの場合は `sudo npm install -g @sakasegawa/ncli` を案内) (no_node → 「https://nodejs.org/ から LTS 版（18以上）をインストールしてください」と案内) (command_not_found → `npm list -g @sakasegawa/ncli` でインストール確認。PATH の問題なら `npm bin -g` で確認してPATHに追加する手順を案内)

---

Step 2: ncli で Notion に OAuth ログインする

**AIが実行すること:** 1. ターミナルで以下を実行:

ncli login

2. ncli が自動でブラウザを開き、Notion の OAuth 認証画面が表示される 3. ユーザーは画面の案内に従って:

• Notion にログイン（未ログインの場合）
• 連携先のワークスペースを選択
• 「Allow access」（アクセスを許可）をクリック

4. 承認が成功するとターミナルに「Logged in as ...」のような表示が出る

**ユーザーに案内するメッセージ:**

ブラウザで Notion の OAuth 画面が開きました。

1. Notion にログインしていない場合はログインしてください
2. アクセスを許可するワークスペースを選択してください
3. 「Allow access」をクリックして承認してください

承認が完了するとブラウザのタブが自動で閉じ、ターミナルにログイン成功のメッセージが表示されます。

⚠️ APIキー（secret_xxx）の入力は不要です。すべてブラウザ上の OAuth で完了します。

**AskQuestionの設定:**

{
  "title": "Step 2: Notion へ OAuth ログイン",
  "questions": [{
    "id": "login_status",
    "prompt": "ncli login の OAuth 認証は完了しましたか？",
    "options": [
      {"id": "logged_in", "label": "ログインできました！"},
      {"id": "browser_not_open", "label": "ブラウザが開かない"},
      {"id": "login_denied", "label": "Notion にログインできない／承認に失敗した"},
      {"id": "wrong_workspace", "label": "別のワークスペースで承認してしまった"}
    ]
  }]
}

(logged_in → Step 3へ) (browser_not_open → 「ターミナルに OAuth 用の URL が表示されているはずです。その URL を手動でブラウザにコピー＆ペーストしてアクセスしてください」と案内) (login_denied → 「Notion アカウントをお持ちでない場合は https://www.notion.so/signup から無料で作成できます。承認後にエラーが出る場合は、もう一度 `ncli login` を実行してやり直してください」と案内) (wrong_workspace → 「`ncli logout` でいったんログアウトしてから `ncli login` をやり直し、正しいワークスペースを選択してください」と案内)

---

Step 3: ncli の動作確認（whoami / search）

**AIが実行すること:** 1. 現在のログイン状態を確認:

ncli whoami

2. ワークスペース内検索のスモークテスト（1〜2件取得できれば成功）:

ncli search ""

または検索キーワードを指定:

ncli search "test"

3. 結果が表示されればワークスペース全体への OAuth 権限が正しく付与されている

**AskQuestionの設定:**

{
  "title": "Step 3: ncli の動作確認",
  "questions": [{
    "id": "smoke_test",
    "prompt": "whoami / search コマンドの結果は正常でしたか？",
    "options": [
      {"id": "ok", "label": "ユーザー名が表示され、検索結果も返ってきた"},
      {"id": "whoami_fail", "label": "whoami で「not logged in」のように表示される"},
      {"id": "search_empty", "label": "検索結果が0件だった"},
      {"id": "other_error", "label": "別のエラーが出た"}
    ]
  }]
}

(ok → Step 4へ) (whoami_fail → 「`ncli login` をもう一度実行してください。複数アカウントを使い分けている場合は、`ncli logout` してからやり直すと確実です」と案内) (search_empty → 「ワークスペース内にページがない場合は当然0件です。テスト用に Notion で1ページ作成してから再度 `ncli search` を試してください」と案内) (other_error → エラーメッセージを確認し、原因を特定して案内)

---

Step 4: MCP設定ファイルに Notion Hosted MCP（OAuth）を追加する

Notion 公式の Hosted MCP は `https://mcp.notion.com/mcp` でホストされており、Streamable HTTP + OAuth で認証します。設定ファイルにはトークンや環境変数を一切記載しません。

**AIが自動で実行すること:**

1. 使用ツールを判定する（Claude Code or Cursor） 2. 対応するMCP設定ファイルに `notion` エントリを追記する（既存の `mcpServers` は保持）

**AIが書き込むMCP設定ファイル:**

**Claude Code の場合:** `~/.