Notion MCP Server — Connect Claude, Cursor & VS Code to Notion

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.

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 →
• 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.

⚡ Quick start

Step 1 — get a Notion token (1 minute). Open 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.)

Step 2 — add the server to your client.

Claude Code

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_paste_your_token_here \
  -- npx -y notion-mcp-server

Cursor

Click the badge (then replace YOUR_NOTION_TOKEN in the generated entry), or add to ~/.cursor/mcp.json yourself:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
    }
  }
}

VS Code (Copilot agent mode)

VS Code prompts for the token on install and stores it as a secret input.

Claude Desktop

Easiest: the one-click extension. Download notion-mcp-server.mcpb from the latest release, double-click it (or drag into Claude Desktop → Settings → Extensions), paste your Notion token when prompted — done. No config files, Node.js not required.

Or via the config file: Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
    }
  }
}

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 — it assumes nothing.

Docker / Podman / OrbStack

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

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.

Step 3 — try it. In a new chat:

"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.

💡 What your AI can do with it

• "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

Full capability list in Features; the complete operation catalog (43 ops) is in the Operations menu.

🧭 Which Notion MCP should you use?

Three options exist. Honest guidance:

	Best for	Auth	Headless / CI	Notes
Notion hosted 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	—	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

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.

Capability	Official Notion MCP (open source)	This server
Tool surface	24 tools (one per endpoint), 17,163 tokens loaded into context	2 tools, 422 tokens — 97% less schema at connection
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

Real-world impact:

• 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.

🪄 Complete walkthrough (no coding required)

What you'll need

1. A Notion account.
2. The Claude Desktop app.
3. About 5 minutes.

Step 1 — Get your Notion token

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.

1. Open 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.

4. Copy the token now — Notion shows it only once. It starts with ntn_. Treat it like a password.

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.

Step 2 — Tell Claude Desktop about the server

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. Sele