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

Give your AI read/write access to Notion with one token and one command. Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed, anything that speaks MCP: it can create pages, query databases, append blocks, apply templates, comment and upload files, in plain language.

Notion ships its own MCP server. Where this one differs:

• It authenticates with a token, so it runs headless. Notion's hosted MCP is OAuth-only and someone has to click "Authorize". This one works in CI, cron jobs, background agents and self-hosted deployments.
• It doesn't spend your context on tool schemas. The official open-source server loads 24 endpoint schemas into the model's context at connection: 17,163 tokens, re-sent with every request for the rest of the session. This one loads three tools, 1,005 tokens — 94% less, 17× smaller — and fetches an operation's schema only when a task actually touches it.
• It doesn't spend your context on answers either. Reading the same pages through both servers, pulling a page's content costs 82% less (26,071 → 4,568 tokens on an 88-block page), a 25-row database query 81% less, a page object 68% less. Notion's raw JSON is mostly id/type wrappers, annotations, and created_by/parent/icon blocks, and none of it reaches the model. That is the half that compounds, because a tool surface is paid once and responses are paid on every call. Measured against a reproducible fixture, with the caveats stated →

Nothing is lost to get there: a database query returns flat name → value rows instead of Notion's raw properties bags (5.3× lighter in the benchmark), and verbose: true gives you the untouched SDK shape whenever you want it — within 4 tokens of what the official server returns, which is how the benchmark proves both are reading the same thing. Batched mutations with atomic rollback, idempotency keys, retry on rate limits and self-healing validation errors are built in, and the comparison below has the rest.

Quick start

1. Get a Notion token. Open app.notion.com/developers/tokens → + New token → name it, pick your workspace → Create token → copy the ntn_… value. A Personal Access Token sees everything you can see, with no per-page sharing. (Page missing or empty? Your admin disabled PATs — see auth alternatives.)

2. Install it.

npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here

add-mcp finds the MCP clients on your machine and writes the config for the ones you pick: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed and a dozen others. Add -g to install at user level instead of the current project, -a claude-code to skip the picker, --all to write every client at once.

Keep the --env flag. Without it the entry is written without a token, and the server starts and then fails every call with an auth error.

Any client that reads an mcpServers block (Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline's settings, Zed, Continue…):

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

Claude Code:

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

Claude Code speaks the 2025-era protocol over stdio unless told otherwise. Set MCP_PROTOCOL_NEGOTIATION=auto in its environment and it probes for MCP 2026-07-28 (stateless requests, cache hints on every list). The server serves both.

Cursor: — click, then replace YOUR_NOTION_TOKEN in the generated entry.

VS Code (Copilot agent mode): — VS Code prompts for the token and stores it as a secret input.

Gemini CLI:

gemini extensions install https://github.com/awkoy/notion-mcp-server

The repo ships a gemini-extension.json, so this installs as an extension: it asks for the token once, keeps it in your system keychain, and starts the server with npx.

Claude Desktop, without Node.js: download notion-mcp-server.mcpb from the latest release and double-click it (or drag it into Settings → Extensions), then paste your token when prompted. Never edited a config file before? The step-by-step walkthrough 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 for stdio. The image is OCI-compliant, so Podman, OrbStack, colima, Rancher Desktop, Finch and nerdctl take the same flags. For a long-running HTTP container see Remote / HTTP transport.

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_write 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."
• "Rewrite that spec page: fix the headings and add a code sample." — markdown round-trip via 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 uploads
• "Look at the screenshot on that bug report and tell me what's wrong." — get_image hands the model the picture itself

The full catalog is the operations menu: 47 operations behind three tools.

Which Notion MCP should you use?

To chat with your Notion in claude.ai's web UI, use Notion's hosted connector: it's one click. Use this server when the agent runs unattended, when context cost matters, or when you want batch and idempotent semantics and your own host.