npm - notion-mcp-server - Versions diffs - 2.10.0 → 2.11.0 - Mend

notion-mcp-server 2.10.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,84 +1,69 @@
-# Notion MCP Server — Connect Claude, Cursor & ChatGPT to Notion via Model Context Protocol
+# Notion MCP Server — Connect Claude, Cursor & VS Code to Notion
+[![npm version](https://img.shields.io/npm/v/notion-mcp-server)](https://www.npmjs.com/package/notion-mcp-server)
+![NPM Downloads](https://img.shields.io/npm/dw/notion-mcp-server)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue)
-![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-purple)
+![Model Context Protocol](https://img.shields.io/badge/MCP-Streamable_HTTP_+_stdio-purple)
 [![notion-mcp-server on Smithery](https://smithery.ai/badge/@awkoy/notion-mcp-server)](https://smithery.ai/server/@awkoy/notion-mcp-server)
-![NPM Downloads](https://img.shields.io/npm/dw/notion-mcp-server)
 ![Stars](https://img.shields.io/github/stars/awkoy/notion-mcp-server)
-An agent-first **Notion MCP server** (Model Context Protocol) that connects Claude, Cursor, ChatGPT, Claude Desktop, Cline, Zed and other MCP-compatible AI clients to Notion. Sign in once with your Notion **Personal Access Token (PAT)** — no per-page sharing dance, no extra integration to set up. Your AI sees the Notion pages you authorize the token for (typically your whole workspace) and can create pages, query databases, append blocks, leave comments, and upload files in natural language.
+Give your AI full read/write access to Notion with **one token and one paste**. This is an agent-first **Notion MCP server**: your AI client (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed — anything that speaks MCP) can create pages, query databases, append blocks, apply templates, comment, and upload files in natural language.
-> **v2.4 — built for AI agents, not REST clients.** Two MCP tools instead of 36 endpoints, batched mutations, idempotency keys, automatic retries on Notion rate limits, self-healing validation errors (now path-sliced to <1KB), slim token-efficient responses, and a markdown shortcut so the model can write a whole page in one call.
+Three reasons it exists when Notion ships its own MCP:
+- **Built for agents, not humans-in-the-loop.** Notion's hosted MCP is OAuth-only — it cannot run headless. This server authenticates with a token, so it works in **CI, cron jobs, background agents, and self-hosted deployments** where nobody can click "Authorize".
+- **97% smaller tool footprint at connection.** Two MCP tools (**422 tokens**) instead of one schema per endpoint — the official open-source server loads **17,163 tokens** of tool schemas before you do anything. Operation schemas load on demand via `notion_describe`, so even a typical multi-operation task stays 85–95% lighter. [Measured, reproducible →](./benchmarks)
+- **The operational stuff is built in.** Batched mutations with atomic rollback, idempotency keys, automatic retry on rate limits, slim token-efficient responses, full markdown round-trip, and self-healing validation errors that let the model fix its own bad payloads in one turn.
 <a href="https://glama.ai/mcp/servers/zrh07hteaa">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/zrh07hteaa/badge" alt="Notion MCP Server on Glama" />
 </a>
-## 📑 Table of Contents
-- [5-minute install (no coding required)](#-5-minute-install-no-coding-required)
-- [Why this server? (vs. the official Notion MCP)](#-why-this-server-vs-the-official-notion-mcp)
-- [Developer install](#-developer-install)
-  - [Authentication: PAT (recommended) vs. Internal Integration](#authentication-pat-recommended-vs-internal-integration)
-  - [Get a Personal Access Token — full walkthrough](#get-a-personal-access-token--full-walkthrough)
-  - [Backward compatibility from v1.x](#backward-compatibility-from-v1x)
-  - [Claude Code / Cursor / Claude Desktop](#claude-code--cursor--claude-desktop)
-  - [Docker / Podman / OrbStack](#docker--podman--orbstack)
-  - [Optional `NOTION_PAGE_ID`](#optional-notion_page_id)
-- [Remote / HTTP transport](#-remote--http-transport)
-- [Features: what this Notion MCP server does](#-features-what-this-notion-mcp-server-does)
-- [MCP tools for Notion (`notion_execute` & `notion_describe`)](#-mcp-tools-for-notion-notion_execute--notion_describe)
-  - [`notion_execute`](#notion_execute)
-  - [`notion_describe`](#notion_describe)
-  - [Operations menu (35 ops, plus one alias)](#operations-menu-35-ops-plus-one-alias)
-- [Development](#-development)
-- [Technical details: how the Notion MCP server is built](#-technical-details-how-the-notion-mcp-server-is-built)
-- [Troubleshooting the Notion MCP server](#-troubleshooting-the-notion-mcp-server)
-- [FAQ: Notion MCP server](#-faq-notion-mcp-server)
-- [Contributing](#-contributing)
-- [License](#-license)
+## ⚡ Quick start
----
+**Step 1 — get a Notion token (1 minute).** Open **[app.notion.com/developers/tokens](https://app.notion.com/developers/tokens)** (the **Personal access tokens** page of Notion's developer portal) → **+ New token** → name it, pick your workspace → **Create token** → copy the `ntn_…` value. That's it — a PAT sees everything *you* can see, no per-page sharing required. (Page missing or empty? Your admin disabled PATs — see [auth alternatives](#authentication-pat-recommended-vs-internal-integration).)
-## 🪄 5-minute install (no coding required)
+<img src="https://raw.githubusercontent.com/awkoy/notion-mcp-server/main/assets/notion-pat-page.png" width="640" alt="Notion developer portal — the Personal access tokens page with the + New token button in the top right">
-You don't need to know what a terminal is. If you can copy text and paste it into two boxes, you can finish this.
+**Step 2 — add the server to your client.**
-### What you'll get
-After setup, you can tell Claude things like:
+### Claude Code
-- *"Make a page in my Personal workspace called 'Q3 plan' and add a checklist of these five items."*
-- *"Find every page in my Tasks database where Status is 'Doing' and tell me which are overdue."*
-- *"Comment on yesterday's meeting notes with a one-paragraph summary."*
+```bash
+claude mcp add notion -s user \
+  -e NOTION_TOKEN=ntn_paste_your_token_here \
+  -- npx -y notion-mcp-server
+```
-Claude reads and writes Notion directly — no copy/paste, no browser tabs.
+### Cursor
-### What you'll need
-1. A Notion account.
-2. The [Claude Desktop app](https://claude.ai/download) installed. (Cursor and Claude Code work too — see [Developer install](#-developer-install).)
-3. About 5 minutes.
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=notion&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm5vdGlvbi1tY3Atc2VydmVyIl0sImVudiI6eyJOT1RJT05fVE9LRU4iOiJZT1VSX05PVElPTl9UT0tFTiJ9fQ==)
-### Step 1 — Get your Notion Personal Access Token
+Click the badge (then replace `YOUR_NOTION_TOKEN` in the generated entry), or add to `~/.cursor/mcp.json` yourself:
-A Personal Access Token (PAT) is like a key that lets the AI act as **you** inside Notion. It can see every page **you** can see — no per-page setup.
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "notion-mcp-server"],
+      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
+    }
+  }
+}
+```
+### VS Code (Copilot agent mode)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Notion_MCP-0098FF?logo=githubcopilot)](https://insiders.vscode.dev/redirect/mcp/install?name=notion&inputs=%5B%7B%22id%22%3A%22notion_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Notion%20Personal%20Access%20Token%20(ntn_...)%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22notion-mcp-server%22%5D%2C%22env%22%3A%7B%22NOTION_TOKEN%22%3A%22%24%7Binput%3Anotion_token%7D%22%7D%7D)
-1. Open the Notion developer portal: **[notion.so/profile/integrations](https://www.notion.so/profile/integrations)** (while logged into Notion). Same page if you go through the app: **Settings → Connections → Develop or manage integrations**.
-2. Open the **Personal access tokens** tab → click **+ New personal access token**.
-3. Give it a name like `Claude`, pick the **workspace** the token should act in, leave the default capabilities checked, and click **Create token**.
-4. **Copy** the token — Notion shows the full value **only once**. It starts with `ntn_`. Treat it like a password.
+VS Code prompts for the token on install and stores it as a secret input.
-> PATs **expire 1 year after creation**. Set a calendar reminder to rotate before then, or auth will start failing.
->
-> Don't see a "Personal access tokens" tab? Your workspace admin may have disabled them — use the [Internal Integration alternative](#authentication-pat-recommended-vs-internal-integration).
->
-> Need more detail (rotation, revocation, what a PAT can/can't do)? See the [full PAT walkthrough](#get-a-personal-access-token--full-walkthrough) further down. Official reference: [Notion PAT guide](https://developers.notion.com/guides/get-started/personal-access-tokens).
+### Claude Desktop
-### Step 2 — Tell Claude Desktop where the server lives
+**Easiest: the one-click extension.** Download [`notion-mcp-server.mcpb` from the latest release](https://github.com/awkoy/notion-mcp-server/releases/latest/download/notion-mcp-server.mcpb), double-click it (or drag into Claude Desktop → Settings → Extensions), paste your Notion token when prompted — done. No config files, Node.js not required.
-1. Open Claude Desktop → click **Claude** (top-left menu on Mac, or the hamburger menu on Windows) → **Settings** → **Developer** → **Edit Config**.
-2. A file called `claude_desktop_config.json` opens in a text editor. **Don't panic at the curly braces** — it's just text. We're going to swap all of it out.
-3. **Select all** the text in that file (`Cmd+A` on Mac, `Ctrl+A` on Windows), **delete it**, then paste the block below.
+**Or via the config file:** Settings → Developer → Edit Config, then add:
 ```json
 {
@@ -86,391 +71,326 @@ A Personal Access Token (PAT) is like a key that lets the AI act as **you** insi
     "notion": {
       "command": "npx",
       "args": ["-y", "notion-mcp-server"],
-      "env": {
-        "NOTION_TOKEN": "ntn_paste_your_token_here"
-      }
+      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
     }
   }
 }
 ```
-> **What is this block?** It tells Claude Desktop how to launch the Notion connector. `npx` is a small tool that downloads and runs the connector automatically the first time — you don't install anything separately, it happens in the background (the first run may take a few seconds). `env` is where your Notion token goes. Leave every quote mark and bracket exactly as shown; the only thing you change is the token.
-4. Replace `ntn_paste_your_token_here` with the token you copied in Step 1 — **leave the quotation marks around it**.
-5. **Save** the file (`Cmd+S` / `Ctrl+S`).
-6. **Quit Claude Desktop completely** (Mac: `Cmd+Q`, not just closing the window — Windows: right-click the tray icon → Quit) and reopen it.
-### Step 2b — Did it work?
-After Claude Desktop reopens, start a new chat and type **`/`** in the message box. You should see `notion_execute` and `notion_describe` appear in the slash-command list. If they don't, the connection didn't take — go back to **Settings → Developer → Edit Config**, check there's no typo in the token (it must stay between the quotation marks), and confirm you fully quit and reopened Claude Desktop. Common pitfalls are also covered in [Troubleshooting](#-troubleshooting-the-notion-mcp-server).
+Quit Claude Desktop fully (`Cmd+Q` / tray → Quit) and reopen. **Never used a config file before?** Follow the [step-by-step walkthrough for non-developers](#-complete-walkthrough-no-coding-required) — it assumes nothing.
-### Step 3 — Try it
+### Docker / Podman / OrbStack
-In a new Claude chat, type:
+```bash
+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
+```
-> *"Use Notion to make a new page called 'Hello from Claude' under my workspace and add a checklist of three things I want to try today."*
+The `-i` flag is required (stdio transport). The image is OCI-compliant — Podman, OrbStack, colima, Rancher Desktop, Finch, and nerdctl all work with the same flags.
-You should see Claude call the `notion_execute` tool and report back with a page link. Click it — your new page is live in Notion.
+**Step 3 — try it.** In a new chat:
-That's it. If something doesn't work, the most common fix is in [Troubleshooting](#-troubleshooting-the-notion-mcp-server) below — usually a token typo or Claude Desktop not being fully quit and reopened. The rest of this README covers Docker, Cursor, Claude Code, and self-hosting for developers.
+> *"Use Notion to make a page called 'Hello from my agent' and add a checklist of three things to try today."*
----
+Your AI calls `notion_execute` and replies with a live page link.
-## ⚡ Why this server? (vs. the official Notion MCP)
+## 💡 What your AI can do with it
-There's a [first-party Notion MCP server](https://github.com/makenotion/notion-mcp-server). It works for simple one-off calls. For agent workloads — repeated queries, bulk mutations, long context windows — it gets expensive fast: one MCP tool per endpoint, no batching, no idempotency, raw response shapes. Those choices add up to real token cost and real latency.
+- *"Find every row in my Tasks database where Status is 'Doing' and tell me which are overdue."* — typed `where` filters, flattened rows
+- *"Rename these 50 pages to the new convention."* — one batched call, 10-way parallel, idempotent retry
+- *"Create a page from my 'Weekly review' template and fill in this summary."* — Notion templates support
+- *"Rewrite that spec page: fix the headings and add a code sample."* — full markdown round-trip (`get_page_markdown` → edit → `update_page_markdown`)
+- *"Comment on yesterday's meeting notes with a one-paragraph summary."*
+- *"Upload this diagram to the design page."* — single- and multi-part file uploads
-This server is designed from the agent's side of the protocol.
+Full capability list in [Features](#-features-what-this-notion-mcp-server-does); the complete operation catalog (43 ops) is in the [Operations menu](#operations-menu-43-ops-plus-one-alias).
-| Capability | Official Notion MCP | **This server (designed for agents)** |
-| --- | --- | --- |
-| **Tool surface** | 22 tools (one per endpoint) loaded into context | **2 tools** (`notion_execute`, `notion_describe`) — the LLM loads ~90% less schema |
-| **Operations covered** | ~22 endpoints | **35 operations** (plus a `trash_page` alias of `archive_page`) across pages, blocks, databases, data sources, comments, users, files |
-| **Primary auth** | Internal Integration token + per-page "Connect" sharing | **Personal Access Token (PAT)** — uses the pages you've authorized for the token, zero per-page Connect step |
-| **Batch mutations** | Not documented | ✅ Universal `{ items: [...] }` envelope; runs up to **10 in parallel** |
-| **Atomic batches + rollback** | Not documented | ✅ `atomic: true` aborts on first failure, best-effort archives entities created earlier |
-| **Idempotency** | Not documented | ✅ `idempotency_key` — same key + same op returns the cached result for 5 minutes |
-| **Rate-limit handling** | Not documented (429s bubble up) | ✅ Shared token-bucket limiter (3 req/s default, configurable via `NOTION_RATE_LIMIT`) + exponential backoff on 429/5xx/timeouts, honors `Retry-After` |
-| **Response shapes** | Raw Notion SDK JSON | **Slim shapers by default** — drops `archived: false`, `created_time`, `last_edited_time`, `in_trash: false`, empty descriptions, etc. `verbose: true` to opt out |
-| **Database queries** | Raw `properties` bag per row | **Flattened** name → primitive map (title, rich_text, number, select, multi_select, status, date, people, files, checkbox, url, email, phone_number, formula, relation, rollup, unique_id, verification, created_by, last_edited_by, timestamps) |
-| **Wire format** | Default SDK serialization | **Compact (un-indented) JSON** — ~30% smaller payloads vs. indented output, identical to parse |
-| **Markdown input** | Page-level markdown editing supported | ✅ `markdown` shortcut on `create_page` / `append_blocks` / `update_block`, full markdown round-trip via `get_page_markdown` / `update_page_markdown`, plus markdown comment bodies — full GFM (paragraphs, headings 1–4, lists, to-dos with nested children, blockquotes, fenced code with language detection, images, dividers, inline bold/italic/strike/code/links) |
-| **File uploads** | Not in the documented tool surface | ✅ `upload_file` handles single-part and multi-part (5 MB chunks) transparently; MIME inferred from filename; rejects `application/octet-stream` |
-| **Validation errors** | Plain error string | **Self-healing**: `{ code, message, path, issues, schema, example, fix }` — agent corrects bad payloads in one round-trip without calling describe |
-| **Notion API version** | Not pinned in client config | Pinned to `2025-09-03` (the modern data-sources line) |
-### Real-world impact
-- **Renaming 50 pages.** Without a batch envelope, the agent issues 50 separate `update-page` MCP calls — each one re-loading the tool schema and serialized through the agent's reasoning loop. With this server, the agent issues one `notion_execute` call with `{ items: [...], concurrency: 10 }`. Wall-clock improvement is roughly an order of magnitude on typical batch sizes; the bigger win is the tokens saved on prompt overhead.
-- **Loading the tool list into the agent's context.** Official server: 22 schema blobs every conversation. This server: 2 schema blobs — and only those 2 ever appear in the agent's tool list, regardless of which of the 35 operations the agent ends up calling.
-- **Reading a 100-row database.** Official server returns the raw Notion `properties` bag per row. This server flattens it; for a typical CRM table this is roughly **5–10× fewer tokens** without losing information.
+## 🧭 Which Notion MCP should you use?
----
+Three options exist. Honest guidance:
-## 🚀 Developer install
+| | Best for | Auth | Headless / CI | Notes |
+| --- | --- | --- | --- | --- |
+| **[Notion hosted MCP](https://developers.notion.com/docs/get-started-with-mcp)** (`mcp.notion.com`) | Interactive chat in claude.ai, ChatGPT, Cursor | OAuth (human must click) | ❌ | First-party, 18 markdown tools, some plan-gated |
+| **[Official open-source server](https://github.com/makenotion/notion-mcp-server)** | — | Token | ✅ | Notion has soft-deprecated it (“may sunset this repository… issues and PRs not actively monitored”) |
+| **This server** | Agents, automation, CI, self-hosting, token-sensitive workloads | Token (PAT) | ✅ | Actively maintained, agent-first design below |
-### Authentication: PAT (recommended) vs. Internal Integration
+If you just want to chat with your Notion in claude.ai's web UI, use Notion's hosted connector — it's one click. Use **this** server when your agent runs unattended, when context/token cost matters, or when you want batch/idempotent semantics and self-hosting.
-There are two ways to authenticate. Both use the `NOTION_TOKEN` env var — only how you obtain the token differs.
+<details>
+<summary><b>Detailed comparison vs. the official open-source server</b></summary>
-| | **Personal Access Token** (recommended) | **Internal Integration** (legacy) |
+| Capability | Official Notion MCP (open source) | **This server** |
 | --- | --- | --- |
-| Where you get it | [notion.so/profile/integrations](https://www.notion.so/profile/integrations) → **Personal access tokens** tab → **+ New personal access token** | [notion.so/profile/integrations/internal](https://www.notion.so/profile/integrations/internal) → **+ New connection** |
-| Token prefix | `ntn_…` | `ntn_…` (new) or `secret_…` (older) |
-| Scope | Everything **you** can see | Only pages where you've clicked **• • • → Connect → \<integration\>** |
-| Setup friction | None — works immediately | Per-page Connect dance for every page or database the agent should touch |
-| When to use | Default. Personal workspaces, team workspaces where you're authorized, prototyping. | When a workspace admin requires explicit per-resource scoping for compliance, or for shared production bots. |
-The rest of this README assumes PAT. Swap in an integration secret if you prefer the scoped model — every command below is identical.
+| **Tool surface** | 24 tools (one per endpoint), 17,163 tokens loaded into context | **2 tools**, 422 tokens — [97% less schema at connection](./benchmarks) |
+| **Operations covered** | ~24 endpoints | **43 operations** (plus a `trash_page` alias) across pages, blocks, databases, data sources, views, templates, comments, users, files |
+| **Batch mutations** | Not documented | ✅ Universal `{ items: [...] }` envelope; up to **10 in parallel** |
+| **Atomic batches + rollback** | Not documented | ✅ `atomic: true` aborts on first failure, best-effort archives entities created earlier |
+| **Idempotency** | Not documented | ✅ `idempotency_key` — same key + op returns the cached result for 5 minutes |
+| **Rate-limit handling** | 429s bubble up | ✅ Token-bucket limiter (3 req/s default) + exponential backoff, honors `Retry-After` |
+| **Response shapes** | Raw Notion SDK JSON | **Slim shapers** drop noise by default; `verbose: true` opts out |
+| **Database queries** | Raw `properties` bag per row | **Flattened** name → primitive map (all 20+ property types) |
+| **Wire format** | Default SDK serialization | **Compact JSON** — ~30% smaller payloads |
+| **Markdown** | Page-level markdown tools | ✅ Markdown accepted by `create_page` / `append_blocks` / `update_block` / comments + full round-trip (`get_page_markdown` / `update_page_markdown`), full GFM |
+| **Templates** | — | ✅ `create_page` from a Notion template + `list_data_source_templates` discovery |
+| **File uploads** | Not in the documented tool surface | ✅ Single- and multi-part (5 MB chunks), MIME inferred |
+| **Validation errors** | Plain error string | **Self-healing**: `{ code, message, path, issues, schema, example, fix }` — corrected in one round-trip |
+| **Notion API version** | — | Pinned `2026-03-11` (data sources, views, templates) |
-> 💡 **Heads-up:** most "object_not_found" errors are a wrong auth choice, not a bug. If your agent reports "Could not find page" on pages you can see in Notion, you're almost certainly using an Internal Integration token that hasn't been Connected to those pages — switch to a PAT.
+**Real-world impact:**
-### Get a Personal Access Token — full walkthrough
+- **Renaming 50 pages** — one `notion_execute` call with `{ items: [...], concurrency: 10 }` instead of 50 separate tool calls through the agent's reasoning loop: roughly an order of magnitude faster, and the prompt-token savings are the bigger win.
+- **Tool list in context** — 2 schema blobs per conversation instead of ~24, no matter which of the 43 operations get called.
+- **Reading a 100-row database** — flattened rows are typically **5–10× fewer tokens** than the raw `properties` bag, with no information loss.
-[Step 1 of the 5-minute install](#step-1--get-your-notion-personal-access-token) covers the happy path. This section covers what surrounds it: capabilities, expiry, revocation, and the admin-disabled fallback.
+</details>
-> 📖 Official: [Notion PAT guide](https://developers.notion.com/guides/get-started/personal-access-tokens) · [Authorization overview](https://developers.notion.com/docs/authorization).
+## 🪄 Complete walkthrough (no coding required)
-#### What a PAT can and can't do
+<details>
+<summary><b>Set up Claude Desktop + Notion in 5 minutes — assumes you've never seen a config file</b></summary>
-| Can | Can't |
-| --- | --- |
-| Read every page you have access to | Access workspaces or pages you personally can't see |
-| Create / update pages and databases in workspaces where you have edit rights | Bypass workspace permission rules |
-| Add comments under your identity | Act as another user |
-| Upload files via the File Upload API | Modify workspace-level admin settings |
+### What you'll need
-A PAT is a **scope = your account**. If you lose edit access to a page, the PAT loses it too. Issue separate tokens to teammates — don't share one.
+1. A Notion account.
+2. The [Claude Desktop app](https://claude.ai/download).
+3. About 5 minutes.
-#### Expiry and rotation
+### Step 1 — Get your Notion token
-**PATs expire 1 year after creation** ([Notion docs](https://developers.notion.com/guides/get-started/personal-access-tokens)). After expiry, every API call returns an auth error until you replace the token. Set a calendar reminder for ~11 months out.
+A Personal Access Token (PAT) is like a key that lets the AI act as **you** inside Notion — it sees every page you can see, with no per-page setup.
-#### Revoking a PAT
+1. Open **[app.notion.com/developers/tokens](https://app.notion.com/developers/tokens)** while logged into Notion — that's the **Personal access tokens** page of Notion's developer portal (also reachable from the app via **Settings → Connections → Develop or manage integrations** → **Personal access tokens** in the sidebar).
+2. Click **+ New token**.
+3. Name it (e.g. `Claude`), pick the workspace, leave the default **Notion API** capability checked, click **Create token**.
-1. Open **[notion.so/profile/integrations](https://www.notion.so/profile/integrations)** → **Personal access tokens** tab.
-2. Find the token by name → **• • • → Revoke**.
-3. Update `NOTION_TOKEN` in your MCP client config and restart the client.
+   <img src="https://raw.githubusercontent.com/awkoy/notion-mcp-server/main/assets/notion-new-token-modal.png" width="460" alt="The New personal access token dialog: enter a token name, pick the workspace it has access to, keep the Notion API capability checked, then press Create token">
-Workspace admins can revoke any user's PATs from **Settings & members → Connections → All personal access tokens**. Revocation is immediate.
+4. **Copy the token now** — Notion shows it only once. It starts with `ntn_`. Treat it like a password.
-#### Workspace admin disabled PATs?
+> PATs **expire 1 year after creation** — set a reminder to rotate. No "Personal access tokens" tab? Your admin disabled them; use the [Internal Integration alternative](#authentication-pat-recommended-vs-internal-integration).
-Some enterprise workspaces only allow scoped Internal Integrations. Two options:
+### Step 2 — Tell Claude Desktop about the server
-1. **Ask your admin to enable PATs** for your account.
-2. **Use the [Internal Integration](#authentication-pat-recommended-vs-internal-integration) path** — same `NOTION_TOKEN` env var; create it at **[notion.so/profile/integrations/internal](https://www.notion.so/profile/integrations/internal) → + New connection**, then click **• • • → Connect** on every page or database you want the agent to touch.
+1. Open Claude Desktop → **Claude** menu (top-left on Mac, hamburger on Windows) → **Settings** → **Developer** → **Edit Config**.
+2. A file named `claude_desktop_config.json` opens. Don't panic at the curly braces — it's just text.
+3. Select all (`Cmd+A` / `Ctrl+A`), delete, and paste:
-### Backward compatibility from v1.x
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "ntn_paste_your_token_here"
+      }
+    }
+  }
+}
+```
-If you ran a v1.x setup, **nothing in your environment needs to change**. Both env vars still work:
+> This block tells Claude Desktop how to launch the connector. `npx` downloads and runs it automatically the first time. The only thing you change is the token.
-| Env var | Status in v2.4 | Notes |
-| --- | --- | --- |
-| `NOTION_TOKEN` | ✅ Required | Accepts **PATs** (`ntn_…`, recommended) and **Internal Integration secrets** (`secret_…` or `ntn_…`, legacy). Identical handling. |
-| `NOTION_PAGE_ID` | ✅ Optional | Still works as the default parent page for `create_page` / `create_database` when no `parent` is passed. v2 added a clean `missing_parent` validation error instead of v1's crash when neither is provided. |
-| `NOTION_RATE_LIMIT` | ✅ New, optional | Requests per second for the shared limiter. Defaults to `3` (Notion's documented per-integration limit). |
-| `NOTION_ALLOWED_OPERATIONS` | ✅ New, optional | Comma-separated allowlist of operations or group presets (`read`, `write`, `destructive`, plus per-domain groups `pages`, `blocks`, `databases`, `data_sources`, `comments`, `users`, `files`). Unset ⇒ all operations enabled. See [Restricting operations](#restricting-operations). |
-| `NOTION_BLOCKED_OPERATIONS` | ✅ New, optional | Comma-separated blocklist (same token vocabulary). Applied after the allowlist, so a blocked operation is always disabled. |
-| `NOTION_READ_ONLY` | ✅ New, optional | Set to `true`/`1`/`yes` to disable every write operation in one switch (equivalent to `NOTION_BLOCKED_OPERATIONS=write`). Composes with the allow/block lists. See [Restricting operations](#restricting-operations). |
-| `NOTION_DAILY_LOG_PAGE_ID` | ✅ Optional | Used only by the daily-log MCP prompt. Ignore if you don't call that prompt. |
+4. Replace `ntn_paste_your_token_here` with your token — **keep the quotation marks**.
+5. Save (`Cmd+S` / `Ctrl+S`).
+6. **Quit Claude Desktop completely** (Mac: `Cmd+Q`; Windows: tray icon → Quit) and reopen it.
-The only v2 break is the **tool surface itself** — v1's `notion_pages`, `notion_blocks`, `notion_database`, `notion_comments`, `notion_users` are replaced by `notion_execute` and `notion_describe`. Modern MCP clients (Claude Code, Cursor, Claude Desktop) rediscover tools at startup, so they pick up the new surface automatically. If your client hard-codes the v1 tool names, see [MIGRATION.md](./MIGRATION.md) for the rename map.
+### Step 3 — Check and try
-A typical v1.x invocation continues to work unchanged:
+Type **`/`** in a new chat — you should see `notion_execute` and `notion_describe` in the list. Then ask:
-```bash
-NOTION_TOKEN=secret_xxx NOTION_PAGE_ID=abc123... node build/index.js
-```
+> *"Use Notion to make a new page called 'Hello from Claude' and add a checklist of three things I want to try today."*
-### Restricting operations
+Claude calls the tool and replies with a page link. If something's off, it's almost always a token typo or Claude Desktop not fully quit — see [Troubleshooting](#-troubleshooting-the-notion-mcp-server).
-By default every operation is available. To limit what an agent can do, set
-`NOTION_ALLOWED_OPERATIONS` (an allowlist) and/or `NOTION_BLOCKED_OPERATIONS` (a
-blocklist). Each is a comma-separated list of **tokens**, where a token is either a
-**group preset** or an exact **operation name**.
+</details>
-**Group presets** (one token expands to many operations):
+## 🔧 Configuration
-| Token | Expands to |
-| --- | --- |
-| `read` | every non-mutating operation |
-| `write` | every mutating operation |
-| `destructive` | operations whose purpose is removal (marked † below) |
-| `pages` `blocks` `databases` `data_sources` `comments` `users` `files` | every operation in that resource family (read **and** write) |
+### Authentication: PAT (recommended) vs. Internal Integration
-**All operations** — use any name directly for a precise allow/blocklist. († = also in the `destructive` group.)
+Both use the same `NOTION_TOKEN` env var — only where you get the token differs.
-| Domain | Read | Write |
+| | **Personal Access Token** (recommended) | **Internal Integration** (scoped) |
 | --- | --- | --- |
-| `pages` | `search_pages` `get_page` `get_page_markdown` | `create_page` `set_page_title` `set_page_property` `set_page_properties` `update_page_markdown` `move_page` `restore_page` `archive_page`† `trash_page`† |
-| `blocks` | `get_block` `get_block_children` | `append_blocks` `update_block` `delete_block`† `batch_mixed_blocks`† |
-| `databases` | `query_database` | `create_database` `update_database` |
-| `data_sources` | `list_data_sources` `get_data_source` | `update_data_source` |
-| `views` | `list_views` `get_view` `query_view` | `create_view` `update_view` `delete_view`† |
-| `comments` | `list_comments` `get_comment` | `add_page_comment` `add_discussion_comment` `update_comment` `delete_comment`† |
-| `users` | `list_users` `get_user` `get_bot_user` `get_self` | — |
-| `files` | `list_file_uploads` `get_file_upload` | `upload_file` |
+| Where | [app.notion.com/developers/tokens](https://app.notion.com/developers/tokens) → **+ New token** | [app.notion.com/developers/connections](https://app.notion.com/developers/connections) → **+ New connection** |
+| Scope | Everything **you** can see | Only pages where you clicked **• • • → Connect → \<integration\>** |
+| Friction | None | Per-page Connect step for every page/database |
+| Use when | Default: personal + team workspaces, prototyping | Admin requires explicit per-resource scoping, or shared production bots |
-Read-only deployment (the most common case):
+> 💡 Most `object_not_found` errors are a wrong auth choice, not a bug: an Internal Integration token that was never Connected to the page. Switch to a PAT.
-```json
-{
-  "mcpServers": {
-    "notion": {
-      "command": "npx",
-      "args": ["-y", "notion-mcp-server"],
-      "env": {
-        "NOTION_TOKEN": "ntn_paste_your_token_here",
-        "NOTION_ALLOWED_OPERATIONS": "read"
-      }
-    }
-  }
-}
-```
+<details>
+<summary><b>PAT details: capabilities, expiry, revocation, admin-disabled fallback</b></summary>
-Allow everything except destructive operations:
+**Can:** read every page you have access to; create/update pages and databases where you have edit rights; comment as you; upload files.
+**Can't:** access pages you can't see; bypass workspace permissions; act as another user; change admin settings. A PAT's scope = your account — if you lose access to a page, so does the PAT. Issue separate tokens per teammate.
-```json
-{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }
-```
+**Expiry:** PATs expire **1 year after creation** ([Notion docs](https://developers.notion.com/guides/get-started/personal-access-tokens)); set a reminder for ~11 months.
-Mix presets and individual ops (read everything, plus append blocks and comments):
+**Revoking:** [app.notion.com/developers/tokens](https://app.notion.com/developers/tokens) → **Revoke** next to the token (immediate). Workspace admins can revoke anyone's from **Settings & members → Connections → All personal access tokens**.
-```json
-{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }
-```
+**Admin disabled PATs?** Ask them to enable, or create an Internal Integration at [app.notion.com/developers/connections](https://app.notion.com/developers/connections) (**+ New connection**) and **• • • → Connect** it to every page the agent should touch — same `NOTION_TOKEN` env var.
-**Rules:** tokens are case-insensitive; unknown tokens are ignored with a warning; the
-blocklist wins on conflict; and if the allowlist is set but resolves to no enabled
-operations (all tokens invalid, or every allowed op also blocked), **all** operations are
-disabled (fail-closed). Disabled operations are hidden from the `notion://operations`
-menu and from `notion_describe`, and `notion_execute` rejects them with
-`operation_not_allowed`.
+Official reference: [PAT guide](https://developers.notion.com/guides/get-started/personal-access-tokens) · [Authorization overview](https://developers.notion.com/docs/authorization).
-**Verifying your configuration.** On startup the server prints one line to **stderr**
-(visible in your MCP client's server logs) summarizing what resolved, e.g.:
+</details>
-```text
-Operation access: 16/37 enabled (allow=read; block=(none))
-```
+### Environment variables
-Unknown tokens and a fail-closed allowlist are logged there too. If the count or the
-`allow`/`block` values aren't what you expect, check that line first.
+| Env var | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `NOTION_TOKEN` | ✅ | — | PAT (`ntn_…`, recommended) or Internal Integration secret (`secret_…` / `ntn_…`) |
+| `NOTION_PAGE_ID` | — | — | Default parent for `create_page` / `create_database` when no `parent` is passed (page → Share → Copy link; ID = last 32 chars) |
+| `NOTION_RATE_LIMIT` | — | `3` | Requests/second for the shared limiter (Notion's documented per-integration limit) |
+| `NOTION_READ_ONLY` | — | — | `true`/`1`/`yes` disables every write operation in one switch |
+| `NOTION_ALLOWED_OPERATIONS` | — | all | Comma-separated allowlist of operations or group presets — see [Restricting operations](#restricting-operations) |
+| `NOTION_BLOCKED_OPERATIONS` | — | — | Comma-separated blocklist (same vocabulary); wins over the allowlist |
+| `HTTPS_PROXY` / `HTTP_PROXY` | — | — | Route Notion API traffic through an HTTP(S) proxy (standard env vars, lowercase also accepted) |
+| `NOTION_DAILY_LOG_PAGE_ID` | — | — | Only used by the daily-log MCP prompt |
-**Limitations** (control is per-operation, not per-parameter):
+HTTP-transport variables (`MCP_TRANSPORT`, `PORT`, `HOST`, `MCP_AUTH_TOKEN`, …) are covered in [Remote / HTTP transport](#-remote--http-transport).
-- The `destructive` group covers operations whose *purpose* is removal (`trash_page`,
-  `archive_page`, `delete_block`, `delete_comment`, `batch_mixed_blocks`). A few *write*
-  operations can also remove content via a parameter — e.g. `update_database` /
-  `update_data_source` accept `in_trash`, and `update_page_markdown` can replace a page
-  body. Blocking `destructive` does **not** disable those write ops. **For a guaranteed
-  no-mutation deployment, use the allowlist** (`NOTION_ALLOWED_OPERATIONS=read`) or the
-  shorthand `NOTION_READ_ONLY=true` — both leave only read operations enabled.
-- MCP *prompts* (e.g. the daily-log prompt) may still reference operations you have
-  disabled. The prompt text is unaffected by the allowlist; the underlying operation is
-  still rejected at execution time.
+> **Upgrading from v1.x?** Your env vars all still work unchanged. The only break is the tool surface (v1's five tools became `notion_execute` + `notion_describe`); modern clients rediscover tools automatically. Details: [MIGRATION.md](./MIGRATION.md).
-### Claude Code / Cursor / Claude Desktop
+### Restricting operations
-**Claude Code:**
+Limit what an agent can do with `NOTION_ALLOWED_OPERATIONS` (allowlist) and/or `NOTION_BLOCKED_OPERATIONS` (blocklist) — each a comma-separated list of **group presets** or exact **operation names**.
-```bash
-claude mcp add notion -s user \
-  -e NOTION_TOKEN=ntn_paste_your_token_here \
-  -- npx -y notion-mcp-server
-```
+| Preset | Expands to |
+| --- | --- |
+| `read` | every non-mutating operation |
+| `write` | every mutating operation |
+| `destructive` | operations whose purpose is removal (`archive_page`/`trash_page`, `delete_block`, `batch_mixed_blocks`, `delete_comment`, `delete_view`) |
+| `pages` `blocks` `databases` `data_sources` `views` `comments` `users` `files` | every operation in that family (read **and** write) |
-**Cursor** (`~/.cursor/mcp.json`) **or Claude Desktop** (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
+Read-only deployment (most common):
 ```json
-{
-  "mcpServers": {
-    "notion": {
-      "command": "npx",
-      "args": ["-y", "notion-mcp-server"],
-      "env": {
-        "NOTION_TOKEN": "ntn_paste_your_token_here"
-      }
-    }
-  }
-}
+{ "env": { "NOTION_TOKEN": "ntn_xxx", "NOTION_ALLOWED_OPERATIONS": "read" } }
 ```
-**Local build (no npx):**
+Everything except destructive ops:
-```bash
-git clone https://github.com/awkoy/notion-mcp-server.git
-cd notion-mcp-server
-npm install && npm run build
-claude mcp add notion -s user \
-  -e NOTION_TOKEN=ntn_paste_your_token_here \
-  -- node "$(pwd)/build/index.js"
+```json
+{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }
 ```
-### Docker / Podman / OrbStack
+Mix presets and individual ops:
-```bash
-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
+```json
+{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }
 ```
-The `-i` flag is required (stdio transport). `-e NOTION_TOKEN` (no `=value`) forwards the env var from the parent process.
+**Rules:** case-insensitive; unknown tokens ignored with a warning; blocklist wins; an allowlist that resolves to zero operations disables **everything** (fail-closed). Disabled operations disappear from `notion_describe` and the `notion://operations` menu, and `notion_execute` rejects them with `operation_not_allowed`.
-For Cursor / Claude Desktop:
+On startup the server logs one line to stderr summarizing what resolved — check it first if the config doesn't behave as expected:
-```json
-{
-  "mcpServers": {
-    "notion": {
-      "command": "docker",
-      "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "ghcr.io/awkoy/notion-mcp-server:latest"],
-      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
-    }
-  }
-}
+```text
+Operation access: 20/44 enabled (allow=read; block=(none))
 ```
-The published image is OCI-compliant — **Podman**, **OrbStack**, **colima**, **Rancher Desktop**, **Finch**, and **nerdctl** all work with the same flags (substitute the runtime's CLI for `docker`). Docker Desktop is not required.
+<details>
+<summary><b>Per-operation reference & limitations</b></summary>
-### Optional `NOTION_PAGE_ID`
-A default parent page for `create_page` / `create_database` when the caller doesn't pass one. Operations that need a parent and don't get one return a clear validation error instead of crashing.
+| Domain | Read | Write |
+| --- | --- | --- |
+| `pages` | `search_pages` `get_page` `get_page_markdown` | `create_page` `set_page_title` `set_page_property` `set_page_properties` `update_page_markdown` `move_page` `restore_page` `archive_page`† `trash_page`† |
+| `blocks` | `get_block` `get_block_children` | `append_blocks` `update_block` `delete_block`† `batch_mixed_blocks`† |
+| `databases` | `query_database` | `create_database` `update_database` |
+| `data_sources` | `list_data_sources` `get_data_source` `list_data_source_templates` | `update_data_source` |
+| `views` | `list_views` `get_view` `query_view` | `create_view` `update_view` `delete_view`† |
+| `comments` | `list_comments` `get_comment` | `add_page_comment` `add_discussion_comment` `update_comment` `delete_comment`† |
+| `users` | `list_users` `get_user` `get_bot_user` `get_self` | — |
+| `files` | `list_file_uploads` `get_file_upload` | `upload_file` |
-To find a page ID: open the page in Notion → **Share → Copy link**. The ID is the last 32 characters of the URL.
+† = also in the `destructive` group.
-```bash
-claude mcp add notion -s user \
-  -e NOTION_TOKEN=ntn_xxx \
-  -e NOTION_PAGE_ID=abc123... \
-  -- npx -y notion-mcp-server
-```
+**Limitations** (control is per-operation, not per-parameter): a few *write* ops can remove content via a parameter — `update_database` / `update_data_source` accept `in_trash`, and `update_page_markdown` can replace a page body. Blocking `destructive` does **not** disable those. For a guaranteed no-mutation deployment use `NOTION_ALLOWED_OPERATIONS=read` or `NOTION_READ_ONLY=true`. MCP *prompts* may still mention disabled operations, but execution is rejected.
----
+</details>
 ## 🌐 Remote / HTTP transport
-By default the server speaks **stdio** (the local connector path above). To run it as a remote/hosted endpoint — for web clients, networked agents, or a shared deployment — set `MCP_TRANSPORT=http`:
+By default the server speaks **stdio** (the local path above). To run it as a remote/hosted endpoint — web clients, networked agents, shared deployments — set `MCP_TRANSPORT=http`:
 ```bash
 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
 ```
-It serves the MCP **Streamable HTTP** protocol at `POST/GET/DELETE /mcp` (stateful sessions via the `mcp-session-id` header) plus an unauthenticated `GET /health`. It's **single-tenant** — every request uses the one `NOTION_TOKEN` the process was started with.
-### Configuration
+It serves MCP **Streamable HTTP** at `POST/GET/DELETE /mcp` (stateful sessions via the `mcp-session-id` header) plus an unauthenticated `GET /health`. It's **single-tenant** — every request acts as the one `NOTION_TOKEN` the process started with.
 | env | default | meaning |
 | --- | --- | --- |
-| `MCP_TRANSPORT` | `stdio` | set to `http` to enable the HTTP transport |
+| `MCP_TRANSPORT` | `stdio` | set to `http` to enable HTTP |
 | `PORT` | `3000` | listen port (`0` = OS-assigned) |
-| `HOST` | `127.0.0.1` | bind address. Loopback by default; set `0.0.0.0` to expose externally (do this only with `MCP_AUTH_TOKEN`) |
+| `HOST` | `127.0.0.1` | bind address; set `0.0.0.0` to expose externally (**only with `MCP_AUTH_TOKEN`**) |
 | `MCP_AUTH_TOKEN` | — | when set, every `/mcp` request must send `Authorization: Bearer <token>` |
 | `MCP_ALLOWED_HOSTS` | localhost + bound host | comma-list for DNS-rebinding `Host` allowlist |
 | `MCP_ALLOWED_ORIGINS` | localhost origins | comma-list for browser `Origin` allowlist |
-> ⚠️ **Single-tenant means whoever reaches `/mcp` acts as your `NOTION_TOKEN`.** On loopback (the default) that's just local processes. Before binding a non-loopback `HOST`, set `MCP_AUTH_TOKEN` (the server logs a warning if you don't) and/or put it behind an authenticating reverse proxy.
+> ⚠️ **Whoever reaches `/mcp` acts as your `NOTION_TOKEN`.** On loopback (the default) that's just local processes. Before binding a non-loopback `HOST`, set `MCP_AUTH_TOKEN` (the server warns if you don't) and/or front it with an authenticating reverse proxy.
+Connect from clients that support headers (Claude Code, Cursor, VS Code):
+```bash
+claude mcp add --transport http notion https://your-host/mcp \
+  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"
+```
-### Try it
+Try it locally:
 ```bash
-# health check
 curl http://127.0.0.1:3000/health
 # -> {"status":"healthy","transport":"http","port":3000}
-# point the MCP Inspector at it
 npx @modelcontextprotocol/inspector --transport http --server-url http://127.0.0.1:3000/mcp
 ```
-In Docker, set the env and publish the port:
+In Docker:
 ```bash
 docker run --rm -e NOTION_TOKEN=ntn_xxx -e MCP_TRANSPORT=http -p 3000:3000 ghcr.io/awkoy/notion-mcp-server
 ```
----
 ## 🌟 Features: what this Notion MCP server does
 - **Two-tool surface** — `notion_execute` (do it) + `notion_describe` (learn the shape). The whole API is one schema deep.
-- **Universal batch envelope** — every mutating op accepts `{ items: [...], atomic?, idempotency_key?, concurrency? }`. Per-item validation, per-item results, summary counts.
+- **Universal batch envelope** — every mutating op accepts `{ items: [...], atomic?, idempotency_key?, concurrency? }` with per-item validation and results.
 - **Atomic batches with best-effort rollback** — `atomic: true` aborts on first failure and archives anything created earlier in the batch.
-- **Idempotency keys** — same `(operation, idempotency_key)` returns the cached batch result for 5 minutes (max 512 entries). Safe to retry on flaky networks.
-- **Rate-limit + retry baked in** — shared token-bucket limiter (3 req/s default, configurable via `NOTION_RATE_LIMIT`); transient SDK failures (429, 5xx, timeouts) auto-retry with exponential backoff and honor `Retry-After`.
-- **Self-healing validation errors** — every failure returns `{ schema, example, fix }`. The model corrects bad payloads in one round-trip — no extra `notion_describe` call needed.
-- **Markdown shortcut** — `create_page` / `append_blocks` / `update_block` / `update_page_markdown` / comment bodies accept a `markdown` string (full GFM: paragraphs, headings 1–4, lists, to-dos with nested children, blockquotes, fenced code with language normalization, dividers, images, inline bold/italic/strike/code/links).
-- **Slim responses + flattened rows** — defaults drop noisy fields and the `query_database` rows flatten each property to a name → primitive map. `verbose: true` per call to get the raw SDK shape. Compact JSON wire format (~30% smaller payloads).
-- **File uploads** — `upload_file` handles single-part and multi-part (5 MB chunks) transparently; auto-detects MIME from filename; rejects `application/octet-stream`.
-- **Opt-in auto-pagination** — pass `paginate: true` on `search_pages`, `list_comments`, or `query_database` and the server walks `next_cursor` for you (capped by `page_limit`, default 10 pages ≈ 1000 items at `page_size: 100`). Other list ops return a single Notion page with `has_more` / `next_cursor`.
-- **Typed `where` filter shorthand** — `query_database` accepts a `where` clause like `{Status: {equals: "Done"}, AND: [...]}` with operator objects (`eq`, `ne`, `gte`, `lte`, `contains`, `starts_with`, etc.); the server compiles it to Notion filter JSON. Pass raw Notion `filter` JSON for edge cases the shorthand can't express (the two fields are mutually exclusive).
-- **Database views** — `list_views` / `get_view` / `query_view` plus `create_view` / `update_view` / `delete_view`. `query_view` runs a view's stored filters/sorts and returns hydrated rows by default (`hydrate: false` for ids only); `create_view` / `update_view` reuse the same `where` shorthand for filters and take a raw `configuration` for type-specific layout (calendar/board/timeline/chart/map require it).
-- **Universal MCP compatibility** — Cursor, Claude Desktop, Claude Code, Cline, Zed, Continue, anything that speaks MCP stdio.
----
-## 📚 MCP tools for Notion (`notion_execute` & `notion_describe`)
-The v2 server exposes exactly **two** MCP tools — your AI client only ever loads these two schemas, regardless of which of the 35 Notion operations you call.
+- **Idempotency keys** — same `(operation, idempotency_key)` returns the cached result for 5 minutes. Safe to retry on flaky networks.
+- **Rate-limit + retry baked in** — token-bucket limiter (3 req/s default, `NOTION_RATE_LIMIT` to change) with exponential backoff on 429/5xx/timeouts, honoring `Retry-After`.
+- **Self-healing validation errors** — failures return `{ schema, example, fix }` so the model corrects bad payloads in one round-trip.
+- **Markdown everywhere** — `create_page` / `append_blocks` / `update_block` / comment bodies accept a `markdown` string (full GFM: headings 1–4, lists, nested to-dos, blockquotes, fenced code with language detection, images, dividers, inline formatting), plus full round-trip via `get_page_markdown` / `update_page_markdown`.
+- **Notion templates** — `create_page` can apply a data source's template (`template: { type: "template_id" | "default" }`), with `list_data_source_templates` to discover template IDs.
+- **Database views** — list/get/query/create/update/delete views; `query_view` runs a view's stored filters/sorts and returns hydrated rows.
+- **Typed `where` filter shorthand** — `query_database` takes `{Status: {equals: "Done"}, AND: [...]}` and compiles it to Notion filter JSON (raw `filter` still accepted for edge cases).
+- **Slim responses + flattened rows** — noisy fields dropped by default, `query_database` rows flattened to name → primitive maps, compact JSON wire format (~30% smaller). `verbose: true` opts out per call.
+- **File uploads** — single-part and multi-part (5 MB chunks) transparently; MIME inferred from filename.
+- **Opt-in auto-pagination** — `paginate: true` on `search_pages` / `list_comments` / `query_database` walks `next_cursor` for you (default cap ≈ 1000 items).
+- **HTTP(S) proxy support** — standard `HTTPS_PROXY` / `HTTP_PROXY` env vars for corporate networks.
+- **Access control** — `NOTION_READ_ONLY` one-switch read-only mode plus per-operation allow/block lists.
+## 📚 MCP tools (`notion_execute` & `notion_describe`)
+The server exposes exactly **two** MCP tools — your client loads two schemas regardless of which of the 43 operations gets called.
 ### `notion_execute`
-Run any Notion operation. Pass `{ operation, payload }` — payload is either a single object, or `{ items: [...] }` for batch mode.
-**Single call:**
+Run any operation: `{ operation, payload }`, where payload is a single object or `{ items: [...] }` for batch mode.
 ```jsonc
+// single call
 {
   "operation": "set_page_title",
   "payload": { "page_id": "<page-id>", "title": "Q3 plan" }
 }
 ```
-**Batch:**
 ```jsonc
+// batch
 {
   "operation": "set_page_title",
   "payload": {
@@ -480,14 +400,13 @@ Run any Notion operation. Pass `{ operation, payload }` — payload is either a
     ],
     "atomic": false,
     "concurrency": 3,
-    "idempotency_key": "rename-pass-2025-05-26"
+    "idempotency_key": "rename-pass-2026-07-02"
   }
 }
 ```
-**Markdown shortcut** (works in `create_page`, `append_blocks`, `update_block`, `update_page_markdown`):
 ```jsonc
+// markdown shortcut (create_page, append_blocks, update_block, update_page_markdown)
 {
   "operation": "create_page",
   "payload": {
@@ -498,125 +417,116 @@ Run any Notion operation. Pass `{ operation, payload }` — payload is either a
 }
 ```
-**Self-healing errors:** if the payload doesn't validate, the response includes the full JSON Schema for that operation plus a working example, so the next call can be corrected without round-tripping through `notion_describe`.
+If a payload doesn't validate, the error response includes the operation's full JSON Schema, a working example, and a `fix` hint — the next call can be corrected without a `notion_describe` round-trip.
 ### `notion_describe`
-Return the JSON Schema + working example for a single operation. Use this when you want to see the shape of a complex op (filter expressions, mixed block batches, full database property definitions) before calling `notion_execute`.
+Returns the JSON Schema + working example for one operation — useful before complex calls (filter expressions, mixed block batches, database property definitions).
 ```jsonc
 { "operation": "query_database" }
 ```
-### Operations menu (41 ops, plus one alias)
+### Operations menu (43 ops, plus one alias)
 | Area | Operations |
 | --- | --- |
 | **Pages** | `create_page`, `get_page`, `set_page_title`, `set_page_property`, `set_page_properties`, `archive_page` (alias: `trash_page`), `restore_page`, `search_pages`, `move_page`, `get_page_markdown`, `update_page_markdown` |
 | **Blocks** | `append_blocks`, `get_block`, `get_block_children`, `update_block`, `delete_block`, `batch_mixed_blocks` |
 | **Databases** | `create_database`, `query_database`, `update_database` |
-| **Data sources** | `list_data_sources`, `get_data_source`, `update_data_source` |
+| **Data sources** | `list_data_sources`, `get_data_source`, `update_data_source`, `list_data_source_templates` |
 | **Views** | `list_views`, `get_view`, `query_view`, `create_view`, `update_view`, `delete_view` |
 | **Comments** | `list_comments`, `add_page_comment`, `add_discussion_comment`, `get_comment`, `update_comment`, `delete_comment` |
-| **Users** | `list_users`, `get_user`, `get_bot_user` |
+| **Users** | `list_users`, `get_user`, `get_bot_user`, `get_self` |
 | **Files** | `upload_file`, `list_file_uploads`, `get_file_upload` |
-The authoritative list (with batchability) is also served as an MCP resource at `notion://operations` — useful as a one-shot cheat sheet for the LLM.
+The authoritative list (with batchability) is served as an MCP resource at `notion://operations`.
 ### MCP resources
-The server exposes three resources, so clients that support resource attachment (`@`-mention) can pull Notion content into context without a tool call:
+Clients that support resource attachment (`@`-mention) can pull Notion content into context without a tool call:
 | Resource URI | Returns |
 | --- | --- |
-| `notion://operations` | Markdown cheat sheet of every enabled operation. |
-| `notion://page/<page_id>` | The page body as markdown. |
-| `notion://database/<data_source_id>` | The data source's schema as JSON. |
-The dynamic page/database resources route through the same auth, rate limiting, and access gating as tool calls — a page disabled by your allow/block config (or `NOTION_READ_ONLY`) returns an error envelope, not content.
----
-## 🛠 Development
-```bash
-git clone https://github.com/awkoy/notion-mcp-server.git
-cd notion-mcp-server
-npm install
-# Set NOTION_TOKEN (and optionally NOTION_PAGE_ID) in a .env file.
-echo "NOTION_TOKEN=ntn_xxx" > .env
-npm run build       # tsc -> build/
-npm test            # vitest smoke suite
-npm run inspector   # MCP inspector against the built binary
-```
+| `notion://operations` | Markdown cheat sheet of every enabled operation |
+| `notion://page/<page_id>` | Page body as markdown |
+| `notion://database/<data_source_id>` | Data source schema as JSON |
----
+Dynamic resources route through the same auth, rate limiting, and access gating as tool calls.
-## 🔧 Technical details: how the Notion MCP server is built
+## ❓ Troubleshooting the Notion MCP server
-- TypeScript + MCP SDK (`^1.29.0`)
-- Notion SDK `@notionhq/client@^5.22.0`, pinned `Notion-Version: 2025-09-03`
-- Zod 4 payload validation; emits draft-7 JSON Schema with `$defs` deduplication for error envelopes
-- Markdown → Notion blocks via the `remark` / `remark-gfm` pipeline
-- Bounded-concurrency batch worker (default 3, max 10)
-- Shared token-bucket rate limiter; `withRetry` wraps every dispatched call with exponential backoff on transient failures
-- In-memory idempotency cache (5-minute TTL, 512 entries)
-- Slim shapers per entity type (`slimPage`, `slimBlock`, `slimDatabase`, `slimDataSource`, `slimUser`, `slimComment`, `slimFileUpload`) with `verbose: true` opt-out
-- Vitest smoke harness covering the markdown parser, slim shapers, schema emitter, dispatcher, batch partial success / atomic rollback / idempotency dedupe (`npm test`)
+- **`object_not_found` / "Could not find …"** — an Internal Integration token only sees pages explicitly Connected to it. Switch to a PAT to skip per-page sharing.
+- **"Notion auth failed" on every call** — token missing, revoked, or expired (PATs expire after 1 year). Check `NOTION_TOKEN` in your client config, then confirm the token is still listed as Active at [app.notion.com/developers/tokens](https://app.notion.com/developers/tokens).
+- **"No parent page configured"** — pass `parent` in the call, or set `NOTION_PAGE_ID`.
+- **`multi_source_database` from `query_database`** — the database has multiple data sources. Call `list_data_sources`, then pass `data_source_id` instead of `database_id`.
+- **Tools don't appear in Claude Desktop** — token typo (must stay inside the quotes) or the app wasn't fully quit (`Cmd+Q`, not window close) before reopening.
+- **Startup logs "Notion auth check failed" but tools work** — the startup check is best-effort; ignore if calls succeed.
+- **Docker exits immediately / "Connection closed"** — the `-i` flag is required: `docker run --rm -i …`.
+- **Docker: "NOTION_TOKEN is not set" despite `-e`** — use `-e NOTION_TOKEN` (forwards from parent env) or `-e NOTION_TOKEN=ntn_xxx`, not `-e NOTION_TOKEN ntn_xxx`.
----
+Still stuck? [GitHub Issues](https://github.com/awkoy/notion-mcp-server/issues) · [Notion API reference](https://developers.notion.com/reference/intro) · [MCP spec](https://modelcontextprotocol.io)
-## ❓ Troubleshooting the Notion MCP server
+## 💬 FAQ: Notion MCP server
-- **"object_not_found" / "Could not find ..."** — the integration token can only see pages explicitly shared with it. Switch to a PAT to skip per-page sharing.
-- **"Notion auth failed" on every call** — the token was missing, revoked, or expired (PATs expire 1 year after creation). Check `NOTION_TOKEN` is set in your MCP client config, then open [notion.so/profile/integrations](https://www.notion.so/profile/integrations) → **Personal access tokens** and confirm yours is still listed and not past its expiry. If it expired, create a new one and update the env var.
-- **"No parent page configured"** — pass `parent` in the call, or set `NOTION_PAGE_ID` to a default.
-- **"multi_source_database" error from `query_database`** — your database has more than one data source. Call `list_data_sources` to get the IDs, then pass `data_source_id` instead of `database_id`.
-- **Server logs "Notion auth check failed" on startup but tools still work** — the startup check is best-effort. If subsequent tool calls succeed, ignore the warning (Claude Code suppresses MCP stderr anyway).
-- **Docker container exits immediately / "Connection closed"** — the `-i` flag is required so Docker keeps stdin open for the MCP stdio transport. `docker run --rm -i ...`, not `docker run --rm ...`.
-- **Docker: "NOTION_TOKEN is not set" despite passing `-e`** — make sure the form is `-e NOTION_TOKEN` (forwards from parent env) or `-e NOTION_TOKEN=ntn_xxx` (inline value), not `-e NOTION_TOKEN ntn_xxx` (treated as two separate args).
+### What is the Notion MCP server and how does it work?
-### Getting help
+A Model Context Protocol server that connects AI assistants — Claude, Cursor, VS Code Copilot, Cline, Zed, Continue, anything that speaks MCP — to your Notion workspace. It runs locally (or in Docker, or as an HTTP endpoint) and exposes two MCP tools the AI calls to read and write Notion. You authenticate once with a Notion token; everything else is natural language.
-- [GitHub Issues](https://github.com/awkoy/notion-mcp-server/issues)
-- [Notion API reference](https://developers.notion.com/reference/intro)
-- [Model Context Protocol spec](https://modelcontextprotocol.io)
+### How do I connect Claude to Notion using MCP?
----
+See the [Quick start](#-quick-start): get a PAT at [app.notion.com/developers/tokens](https://app.notion.com/developers/tokens), then one `claude mcp add` command (Claude Code) or one JSON paste (Claude Desktop). Non-developers: the [complete walkthrough](#-complete-walkthrough-no-coding-required) assumes nothing.
-## 💬 FAQ: Notion MCP server
+### What's the difference between this and Notion's official MCP?
-### What is the Notion MCP server and how does it work?
+Notion's **hosted** MCP (`mcp.notion.com`) is OAuth-only and built for interactive chat — it can't run headless. Their **open-source** server is soft-deprecated and exposes one tool per endpoint. This server authenticates with a token (works in CI/automation), exposes 2 tools dispatching 43 operations, batches mutations with idempotency and retries, and slims responses to cut token cost. See [Which Notion MCP should you use?](#-which-notion-mcp-should-you-use).
-The Notion MCP server is a Model Context Protocol (MCP) server that connects AI assistants — Claude, Cursor, ChatGPT, Claude Desktop, Cline, Zed, Continue, anything that speaks MCP — to your Notion workspace. It runs locally (or in Docker) and exposes two MCP tools (`notion_execute`, `notion_describe`) that the AI calls to read and write Notion. You authenticate once with a Notion Personal Access Token; everything else is natural language.
+### Can I use it with Cursor, VS Code, ChatGPT, or Cline?
-### How do I connect Claude to Notion using MCP?
+Cursor, VS Code (Copilot agent mode), Cline, Zed, Continue: yes — install badges and config blocks are in the [Quick start](#-quick-start). ChatGPT's built-in connectors require OAuth-hosted servers, so use Notion's hosted MCP there; developers can still reach this server from the OpenAI API's `mcp` tool by pointing it at a self-hosted [HTTP endpoint](#-remote--http-transport) with a bearer token.
-Follow the [5-minute install](#-5-minute-install-no-coding-required) above. The short version: get a Notion Personal Access Token at [notion.so/profile/integrations](https://www.notion.so/profile/integrations) → **Personal access tokens** tab → **+ New personal access token**, then paste it into Claude Desktop's `claude_desktop_config.json` (Settings → Developer → Edit Config). Quit and reopen Claude Desktop and you can ask it to create or read Notion pages directly.
+### Is it safe to give an AI my Notion token?
-### What is a Notion Personal Access Token and how do I get one?
+The token lives in your MCP client's local config and is only sent to `api.notion.com` over HTTPS. The server is open source — read every line. A PAT has the same access you do, so don't paste it into untrusted clients, and revoke it at [app.notion.com/developers/tokens](https://app.notion.com/developers/tokens) if a laptop is lost. For agents that should never write, set `NOTION_READ_ONLY=true`.
-A Personal Access Token (PAT) is a key that lets an app act as **you** inside Notion. It can see every page you can see — no per-page "Connect" step required. Generate one at **[notion.so/profile/integrations](https://www.notion.so/profile/integrations) → Personal access tokens → + New personal access token**. The token starts with `ntn_…` and expires 1 year after creation. Treat it like a password; don't commit it to git or share it publicly. See the [full walkthrough](#get-a-personal-access-token--full-walkthrough) for capabilities, rotation, and admin restrictions, or the [official Notion guide](https://developers.notion.com/guides/get-started/personal-access-tokens).
+### Does it work with self-hosted or local-only LLMs?
-### What's the difference between this Notion MCP server and the official Notion MCP?
+Yes — anything that speaks MCP stdio (or Streamable HTTP) works. The server doesn't care what's on the other side of the protocol.
-The official Notion MCP server exposes one MCP tool per REST endpoint (22 tools), uses an Internal Integration token (which requires per-page sharing in Notion's UI), and returns raw Notion JSON. This server exposes two tools that dispatch 36 named operations, defaults to a Personal Access Token (no per-page setup), batches mutations, retries on rate limits, and slims responses to cut token usage. See the [full comparison table](#-why-this-server-vs-the-official-notion-mcp).
+## 🛠 Development
-### Can I use this Notion MCP server with Cursor, ChatGPT, or Cline?
+```bash
+git clone https://github.com/awkoy/notion-mcp-server.git
+cd notion-mcp-server
+npm install
+echo "NOTION_TOKEN=ntn_xxx" > .env
-Yes. Anything that speaks the MCP stdio protocol works: Claude Desktop, Claude Code, Cursor, Cline, Zed, Continue, and self-hosted clients. Cursor uses `~/.cursor/mcp.json`; the config block is in the [Developer install](#-developer-install) section. ChatGPT support depends on the client you're using — any wrapper that supports MCP servers will work.
+npm run build       # tsc -> build/
+npm test            # vitest suite
+npm run inspector   # MCP inspector against the built binary
+```
-### Is it safe to give an AI my Notion token?
+Local build instead of npx:
-The token is stored locally in your MCP client's config file and only sent to the Notion API (over HTTPS). It never leaves your machine except to talk to `api.notion.com`. The server itself is open source — you can read every line. That said, a PAT has the same access your account does, so don't paste it into untrusted clients, and revoke it at [notion.so/profile/integrations](https://www.notion.so/profile/integrations) → Personal access tokens if a laptop is lost.
+```bash
+claude mcp add notion -s user \
+  -e NOTION_TOKEN=ntn_xxx \
+  -- node "$(pwd)/build/index.js"
+```
-### Does this work with self-hosted or local-only LLMs?
+<details>
+<summary><b>Technical details: how it's built</b></summary>
-Yes, as long as the LLM client supports MCP stdio (or you run a wrapper that bridges it). The server doesn't care what's on the other side of the protocol.
+- TypeScript + MCP SDK (`^1.29.0`); stdio + Streamable HTTP transports
+- Notion SDK `@notionhq/client@^5.22.0`, pinned `Notion-Version: 2026-03-11`
+- Zod 4 payload validation; emits draft-7 JSON Schema with `$defs` deduplication for error envelopes
+- Markdown → Notion blocks via `remark` / `remark-gfm`
+- Bounded-concurrency batch worker (default 3, max 10); shared token-bucket rate limiter; `withRetry` with exponential backoff around every dispatched call
+- In-memory idempotency cache (5-minute TTL, 512 entries)
+- Slim shapers per entity type with `verbose: true` opt-out
+- Vitest suite covering the markdown parser, shapers, schema emitter, dispatcher, batch semantics (partial success / atomic rollback / idempotency), access control, and HTTP transport
----
+</details>
 ## 🤝 Contributing
@@ -625,3 +535,7 @@ PRs welcome. Fork → branch → commit → push → PR. Run `npm test` before s
 ## 📄 License
 MIT — see [LICENSE](./LICENSE).
+---
+mcp-name: io.github.awkoy/notion-mcp-server

package/build/schema/database.js CHANGED Viewed

@@ -125,9 +125,9 @@ export const RELATION_DB_PROPERTY_SCHEMA = z.object({
     type: z.literal("relation").describe("Relation property type"),
     relation: z
         .object({
-        database_id: z
+        data_source_id: z
             .string()
-            .describe("The ID of the database this relation refers to"),
+            .describe("The ID of the data source this relation refers to"),
         synced_property_name: z
             .string()
             .optional()

package/package.json CHANGED Viewed

@@ -1,6 +1,7 @@
 {
   "name": "notion-mcp-server",
-  "version": "2.10.0",
+  "version": "2.11.0",
+  "mcpName": "io.github.awkoy/notion-mcp-server",
   "type": "module",
   "bin": {
     "notion-mcp-server": "build/index.js"
@@ -52,7 +53,7 @@
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "shx": "^0.4.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"