Notion MCP Server README

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 → + 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:

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

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

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

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

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. Without it, path sources are off over HTTP, and over stdio a path is refused when it goes through a dot-named file or directory (~/.ssh, ~/.aws, .env) or lies under a system or app-data folder (/proc, /dev, ~/Library, %APPDATA%), where MCP clients keep your token. NOTION_UPLOAD_ROOT=/ turns the limit off. Inside a root every file is readable, .env and .git included, so over HTTP pick a root that holds only files you would hand to whoever can call the server.
• URLs. http and https only. Every hop, redirects included, must resolve to a public address, so loopback, private networks and cloud metadata endpoints are refused; NOTION_UPLOAD_ALLOW_PRIVATE_URLS=true lifts that for an intranet. The fetch stops after NOTION_UPLOAD_URL_TIMEOUT_MS (30 s) or once the body passes the size limit.

Notion's signed file URLs are about 500 tokens each and expire within an hour. NOTION_FILE_URLS=ref replaces them in responses with short notion-file: refs that get_file_url and get_image resolve on demand. How refs work →

Remote / HTTP transport

The server speaks stdio by default. Set MCP_TRANSPORT=http to run it as a Streamable HTTP endpoint for web clients, networked agents and shared deployments:

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

⚠️ Whoever reaches /mcp acts as your NOTION_TOKEN. On loopback, the default, that means local processes only. A non-loopback HOST refuses to start without MCP_AUTH_TOKEN; put TLS in front of it too.

Over HTTP, upload_file takes no local paths unless NOTION_UPLOAD_ROOT is set, since the caller may not be on the server's machine. Base64 and URL sources work as usual, see Files.

claude mcp add --transport http notion https://your-host/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Docker, health checks and protocol versions: docs/http-transport.md.

Tools and operations

Three tools, whichever of the 46 operations you end up calling: notion_read runs reads, notion_write runs writes, and notion_describe returns an operation's JSON Schema with a working example. Every id field also accepts a Notion URL, so paste what Share → Copy link gives you. Call examples, batch options and MCP resources: docs/operations.md.

Per-tool permissions

The read/write split lets you approve reads once and keep writes behind a prompt. In Claude Code's settings.json (where notion is whatever you named the server):

{ "permissions": { "allow": ["mcp__notion__notion_read", "mcp__notion__notion_describe"] } }

Operations menu (46 ops, plus two aliases)

FAQ

Does it work on the Notion Free plan? Yes. A workspace owner can create a Personal Access Token on every plan, and the server needs nothing else.

Is there a Notion MCP server without OAuth? This one. It authenticates with a token, so nobody has to click Authorize. Notion's hosted MCP skips OAuth only on Business and Enterprise, with an MCP token a workspace owner creates.

Which clients does it work with? Any MCP client: Claude Code, Claude Desktop, Cursor, VS Code (Copilot agent mode), Codex, Gemini CLI, Cline, Windsurf, Zed, Continue, and local models through any MCP host. More in the FAQ.

Troubleshooting

• "Notion auth failed" on every call: the token is missing, revoked or expired. Check NOTION_TOKEN in your client config, then that the token is still active at app.notion.com/developers/tokens. Installed with add-mcp without --env? Re-run it with the flag.
• object_not_found / "Could not find …": an Internal Integration only sees pages Connected to it. Connect the page, or switch to a PAT.
• "No parent page configured": pass parent in the call, or set NOTION_PAGE_ID.
• multi_source_database: the database has several data sources. Call list_data_sources, then pass a data_source_id instead of the database_id.
• A successful result carries warnings: the call ran. Each entry names a field that was ignored or a property name that was corrected.
• Tools don't appear in Claude Desktop: a typo in the token (it must stay inside the quotes), or the app wasn't fully quit (Cmd+Q) before reopening.
• Startup logs "Notion auth check failed" but tools work: the startup check is best effort; ignore it if calls succeed.
• Docker exits at once or says "NOTION_TOKEN is not set": add -i, and write -e NOTION_TOKEN or -e NOTION_TOKEN=ntn_xxx, not -e NOTION_TOKEN ntn_xxx.

Still stuck? Check the FAQ or open a GitHub issue.

Privacy

The server runs on your machine or your own host and talks only to api.notion.com, over HTTPS, with the token you configure (or through your proxy when HTTPS_PROXY is set). No telemetry, no analytics, no server of ours in the path. The token stays where your MCP client keeps it. get_image fetches only the signed URLs Notion returns for files it hosts. upload_file reads a local file or fetches a URL only when asked to, and refuses URLs that resolve to private or loopback addresses. Notion's own handling of your data is covered by Notion's privacy policy.

Development

git clone https://github.com/awkoy/notion-mcp-server.git && cd notion-mcp-server
npm install && npm run build && npm test

Architecture, running a local build in a client, and the end-to-end test against a real workspace: docs/development.md. PRs are welcome; run npm test before opening one.

License

MIT — see LICENSE.

mcp-name: io.github.awkoy/notion-mcp-server