/setup-notion.en

description: "Lesson command"
duration: "~10 min"
prerequisites: ["Have a Notion account (free plan OK)", "Browser available", "Node.js 18 or higher"]
level: "beginner"
tags: ["setup", "notion", "ncli", "mcp", "oauth"]
nonInteractiveMode: incompatible

Notion CLI (ncli) + Hosted MCP Setup (OAuth-only)

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-notion` to display progress 2. Auto-detect existing configuration:

• Run `which ncli` to check if ncli is already installed
• For Claude Code: check if a `notion` server is defined in `~/.claude/mcp_settings.json`
• For Cursor: check if a `notion` server is defined in `~/.cursor/mcp.json`
• If ncli is installed and MCP is configured, you can just run Step 6 (connection test) and mark it complete

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Connect ncli (Notion CLI) and Notion's official Hosted MCP via **OAuth**, so you can operate Notion from the terminal and from MCP-aware tools | | Duration | ~10 minutes | | Prerequisites | Notion account (free plan OK), Node.js 18 or higher, browser | | Skill Level | No CLI commands needed (everything is auto-run by AI + a single browser-based OAuth approval) | | Auth Method | **This setup uses OAuth only** (no API keys required).<br>Note: a few legacy scripts (e.g. `tools/run_lesson_14_11.py`) still require `NOTION_API_KEY`. See `.env.example` for details. |

**Session flow:** 1. Install ncli (@sakasegawa/ncli) (AI auto-runs) 2. Run `ncli login` and approve Notion's OAuth in the browser 3. Verify with `ncli whoami` / `ncli search` 4. Add Notion Hosted MCP (OAuth) to your MCP configuration file (AI writes it automatically) 5. Restart Claude Code / Cursor and approve the OAuth dialog on first use 6. MCP connection test

> **Why Hosted MCP + OAuth?** The legacy Internal Integration Token flow forced you to create an integration in Notion and individually share each page via "Add connections". With OAuth, a single browser login grants workspace-wide access, so **for this Hosted MCP flow** per-page sharing is **not required**. If you still need to run legacy scripts that read `NOTION_API_KEY` directly (e.g. `tools/run_lesson_14_11.py`), keep using an Internal Integration Token alongside this OAuth setup.

> **Hint**: If the AI's response stops midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "which_tool", "label": "I want to confirm whether I'm using Claude Code or Cursor"},
      {"id": "different_lesson", "label": "I want to go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (check_prereq -> Guide: "You're ready if you have a Notion account (free plan OK), can log in via your browser, and have Node.js 18 or higher installed.") (which_tool -> Explain: "The MCP configuration file location differs between Claude Code and Cursor. Step 4 will guide you through the steps for each.") (different_lesson -> Display module list)

---

Step 1: Install ncli (Notion CLI)

**What the AI does:** 1. Check Node.js version: `node --version` (18 or higher required) 2. Check if ncli is already installed: `which ncli` 3. If not installed, run the following command:

npm install -g @sakasegawa/ncli

4. After installation, verify with `ncli --version`

**AskQuestion configuration:**

{
  "title": "Step 1: Install ncli",
  "questions": [{
    "id": "ncli_status",
    "prompt": "ncli installation has been executed. Please check the result.",
    "options": [
      {"id": "installed", "label": "Installed successfully!"},
      {"id": "npm_error", "label": "Got an error with npm install"},
      {"id": "no_node", "label": "Node.js is not installed"},
      {"id": "command_not_found", "label": "ncli command not found"}
    ]
  }]
}

(installed -> Proceed to Step 2) (npm_error -> Run `npm cache clean --force` and retry. If it's a permissions error, guide to `sudo npm install -g @sakasegawa/ncli`) (no_node -> Guide: "Please install the LTS version (18 or higher) from https://nodejs.org/") (command_not_found -> Check installation with `npm list -g @sakasegawa/ncli`. If it's a PATH issue, check with `npm bin -g` and guide on adding it to PATH)

---

Step 2: Log in to Notion via OAuth using ncli

**What the AI does:** 1. Run the following in the terminal:

ncli login

2. ncli automatically opens the browser to Notion's OAuth screen 3. The user follows the on-screen flow:

• Log in to Notion (if not already)
• Select the workspace to grant access to
• Click "Allow access"

4. On success, the terminal shows a message like "Logged in as ..."

**Message to display to the user:**

The Notion OAuth screen has opened in your browser.

1. If you're not logged in to Notion, log in
2. Select the workspace you want to grant access to
3. Click "Allow access" to approve

After approval, the browser tab closes automatically and the terminal shows a successful login message.

No API key (secret_xxx) input is needed. Everything is completed via the browser-based OAuth flow.

**AskQuestion configuration:**

{
  "title": "Step 2: OAuth login to Notion",
  "questions": [{
    "id": "login_status",
    "prompt": "Is the OAuth flow for ncli login complete?",
    "options": [
      {"id": "logged_in", "label": "Logged in successfully!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "login_denied", "label": "I can't log in to Notion / approval failed"},
      {"id": "wrong_workspace", "label": "I approved the wrong workspace"}
    ]
  }]
}

(logged_in -> Pr