Notion MCP Server

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

notion-mcp-server is a Model Context Protocol (MCP) server that gives Claude Code, Claude Desktop, Cursor, VS Code, Codex and any other MCP client read/write access to Notion with one token. Your AI can search, create and edit pages, query databases, comment and upload files, in plain language.

• Token auth on every Notion plan, Free included. No browser sign-in, so it also runs headless: in CI, cron jobs, background agents and on your own server.
• Light on context. Its three tools cost 1,005 tokens at connection, against 17,163 for Notion's open-source server, and page reads come back 82% smaller. Benchmark →
• Built for agents. Batched writes with atomic rollback and idempotency keys, retry on rate limits, markdown in and out, and errors that tell the model how to fix the call.

Quick start

1. Get a Notion token. Open [app.notion.com/developers/tokens](https://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. Can't create one? See the other token option.

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 more. Add -g to install for your user instead of the current project.

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

Or install in one click:

%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)

• Cursor: replace YOUR_NOTION_TOKEN in the generated entry.
• VS Code (Copilot agent mode): it asks for the token and stores it as a secret.
• Claude Desktop: double-click the .mcpb file (or drag it into Settings → Extensions) and paste your token. No Node.js needed. New to all this? The step-by-step walkthrough assumes nothing.

Using Claude Code? Install it as a plugin instead. The plugin bundles the server with a Notion workflow skill, which teaches Claude when to search, how to filter a database with where, and how to batch writes. Claude Code asks for the token when you install it (or later with /plugin configure notion-mcp-server@awkoy) and keeps it in your system keychain:

/plugin marketplace add awkoy/notion-mcp-server

/plugin install notion-mcp-server@awkoy

The plugin runs the npm release that matches its own version and needs Node.js 22 or later. It also offers a default parent page and a read-only switch; the plugin's README has the details.

Manual setup: JSON config, Claude Code, Codex, Gemini CLI, Docker

Any client that reads an `mcpServers` block (Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline, 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

Codex (~/.codex/config.toml):

[mcp_servers.notion]

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

Gemini CLI: gemini extensions install https://github.com/awkoy/notion-mcp-server asks for the token once and keeps it in your system keychain.

Docker (Podman, OrbStack and colima take the same flags; -i is required for stdio):

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

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 link to the new page.

What you can ask

• *"Find every row in my Tasks database where Status is 'Doing' and tell me which are overdue."*
• *"Rename these 50 pages to the new convention."* One batched call, not 50.
• *"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."* The page round-trips as markdown.
• *"Comment on yesterday's meeting notes with a one-paragraph summary."*
• *"Upload this diagram to the design page."*
• *"Look at the screenshot on that bug report and tell me what's wrong."* The model gets the image itself.

Which Notion MCP should you use?

To chat with Notion in claude.ai or ChatGPT, Notion's hosted connector is one click. Use this server when an agent runs unattended, when your plan has no MCP tokens, when context cost matters, or when you want it on your own host. Detailed comparison →

Configuration

Token: PAT or internal integration

Both go in the same NOTION_TOKEN env var; only where you get them differs.

• Who can create a PAT. Workspace owners always can. On Free and Business plans only owners can by default, on Plus every member can, and admins can change the policy on Business and Enterprise. Guests can't.
• Expiry and revoking. You pick the lifetime when you create it, a year at most. Revoke it on the same tokens page; it stops working immediately. Details: Notion's PAT guide.
• `object_not_found` on a page you can see? That's an Internal Integration that was never Connected to the page. Connect it, or switch to a PAT.

Environment variables

HTTP variables are in Remote / HTTP transport. Upgrading from v1 or v2? Every env var still works; the tool names changed, see MIGRATION.md.

Restricting operations

NOTION_READ_ONLY=true turns off every write. For finer control, NOTION_ALLOWED_OPERATIONS and NOTION_BLOCKED_OPERATIONS take comma-separated operation names or presets: read, write, destructive (archive, trash and delete), or a family (pages, blocks, databases, data_sources, views, comments, users, files). The blocklist wins.

{ "env": { "NOTION_ALLOWED_OPERATIONS": "read" } }                       // read-only

{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } } // everything except removals { "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }

Disabled operations disappear from the tool schemas, so the model never sees them. The server prints what resolved at startup, for example Operation access: 22/48 enabled (allow=read; block=(none)).

To be asked instead of blocked, set NOTION_CONFIRM_DESTRUCTIVE=true: before a destructive operation runs, your client shows a yes/no dialog naming the target. The client has to support MCP elicitation. The full rules, the per-operation list and the limits of per-operation control are in docs/configuration.md.

Files

upload_file accepts base64, a public URL or a local path, up to NOTION_UPLOAD_MAX_BYTES (1 GiB by default). Since the model picks the source, the server guards the two it reads itself:

• Local paths. Set NOTION_UPLOAD_ROOT to the directory uploads may come from; paths outside it are refused, symlinks included.