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".
• 94% smaller tool footprint at connection. Three MCP tools (1,005 tokens, the operation menus included) 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 75–90% 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.

Gemini CLI

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

The repo ships a gemini-extension.json, so Gemini CLI installs it as an extension: it asks for your Notion token once (kept in your system keychain) and starts the server with npx.

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. For a long-running HTTP container (and the health check that goes with it), see Remote / HTTP transport.

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_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." — 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
• "Look at the screenshot on that bug report and tell me what's wrong." — get_image hands the model the picture itself

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

🧭 Which Notion MCP should you use?

Three options exist. Honest guidance:

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.

🪄 Complete walkthrough (no coding required)

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

🔧 Configuration

Authentication: PAT (recommended) vs. Internal Integration

Both use the same NOTION_TOKEN env var — only where you get the token differs.

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

Environment variables

HTTP-transport variables (MCP_TRANSPORT, PORT, HOST, MCP_AUTH_TOKEN, …) are covered in Remote / HTTP transport.

Upgrading from v1.x or v2.x? Your env vars all still work unchanged. The only break is the tool surface (v1's five tools, then v2's notion_execute, became notion_read + notion_write; notion_describe is unchanged); modern clients rediscover tools automatically. Details: MIGRATION.md.

Restricting operations

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.

Read-only deployment (most common):

{ "env": { "NOTION_TOKEN": "ntn_xxx", "NOTION_ALLOWED_OPERATIONS": "read" } }

Everything except destructive ops:

{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }

Mix presets and individual ops:

{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }

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 the tools' operation enums, from notion_describe and from the notion://operations menu, so a call naming one fails validation before it runs; when no write operation is enabled (NOTION_READ_ONLY, or an allowlist of reads) notion_write is not advertised at all.

On startup the server logs one line to stderr summarizing what resolved — check it first if the config doesn't behave as expected:

Operation access: 22/48 enabled (allow=read; block=(none))

Confirm instead of block. NOTION_CONFIRM_DESTRUCTIVE=true keeps destructive operations enabled but makes notion_write ask you before running one, through MCP elicitation: a yes/no dialog in your client that names the operation and its target — the page, database, data source or block title when one retrieve can fetch it (bounded to 5 s), otherwise the id; for a batch, how many items. Restores (restore_page, delete_database / delete_data_source with in_trash: false) and a batch_mixed_blocks call with no delete entry do not prompt, and a blocked operation is still rejected with operation_not_allowed before anyone is asked. Decline, cancel or answer no and the call returns confirmation_declined; the server instructions tell the model not to retry it and to ask you instead. A client that has not declared the elicitation capability gets confirmation_unavailable rather than a silent run — use a client that supports elicitation, unset the variable, or block destructive operations outright with NOTION_BLOCKED_OPERATIONS=destructive.

Files

Uploads. upload_file takes its bytes as base64, a public url, or a local path the server reads directly. A path source can read any file the server process can, so when a model composes the path set NOTION_UPLOAD_ROOT to confine it: relative paths resolve inside the root, and symlinks are resolved before the check so they cannot point out of it.

File URLs. Notion mints a fresh signed S3 URL for every hosted file on every read — about 1,650 characters (~500 tokens), valid for an hour, different each time, and easy for a small model to mangle. NOTION_FILE_URLS=ref replaces them in the slim responses (get_page, search_pages, query_database, query_view, get_block, get_block_children, …) with short, stable refs:

Two read operations turn a ref back into content. Both re-read the object through the Notion API, so a ref stays valid for as long as the file does:

get_image fetches only the URL Notion returned for a Notion-hosted file, never a URL supplied by the caller — so it cannot be steered at a LAN, a cloud metadata endpoint, or an exfil host. External URLs (linked images, external files) are short and stable already: they pass through untouched in either mode, and get_image returns them as text rather than fetching them. get_page_markdown is Notion's own rendered markdown and is not rewritten. The default, full, leaves every response as before.

🌐 Remote / HTTP transport

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:

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

⚠️ 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):

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

Try it locally:

curl http://127.0.0.1:3000/health
# -> {"status":"healthy","transport":"http","port":3000}
npx @modelcontextprotocol/inspector --transport http --server-url http://127.0.0.1:3000/mcp

In Docker:

docker run --rm -e NOTION_TOKEN=ntn_xxx -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=change-me \
  -p 3000:3000 ghcr.io/awkoy/notion-mcp-server

HOST=0.0.0.0 is what makes the published port reachable — inside the container 127.0.0.1 is the container's own loopback — and a non-loopback bind is exactly where MCP_AUTH_TOKEN matters.

Health check. The image ships without a HEALTHCHECK: it starts in stdio mode, where nothing listens, so a built-in probe of /health would mark every stdio container unhealthy. For an HTTP deployment add one yourself — the same command sits in the Dockerfile, commented out:

docker run --rm -e NOTION_TOKEN=ntn_xxx -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=change-me \
  -p 3000:3000 \
  --health-cmd "node -e \"fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"" \
  --health-interval 30s --health-timeout 3s --health-start-period 5s --health-retries 3 \
  ghcr.io/awkoy/notion-mcp-server

Or in Compose:

services:
  notion-mcp-server:
    image: ghcr.io/awkoy/notion-mcp-server:latest
    environment:
      NOTION_TOKEN: ${NOTION_TOKEN:?NOTION_TOKEN is required}
      MCP_TRANSPORT: http
      HOST: 0.0.0.0
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN:?MCP_AUTH_TOKEN is required}
    ports: ["3000:3000"]
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 3s
      start_period: 5s
      retries: 3

🌟 Features: what this Notion MCP server does

• Three-tool surface — notion_read (look), notion_write (change), notion_describe (learn the shape). Each tool's operation is an enum of what it runs, so the tool list is the menu and your client can auto-approve reads while writes still ask.
• 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 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, tables, 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.
• Plain property values — a database row's properties take plain values: { Status: "Done", "Due Date": "2026-10-01", Tags: ["a", "b"], Done: true, Notes: null }. The server reads the data source's schema (cached for 5 minutes) and types each value; title always addresses the title property, an unknown property name or status option is rejected with the valid names, and the full Notion shapes still work. get_data_source lists select / multi_select / status options inline.
• Typed where filter shorthand — query_database takes { Status: "Done", Priority: { in: ["High", "Medium"] }, OR: [...] }, resolves each property's type from the data source's schema and compiles it to Notion filter JSON; sorts: ["-Due Date"] sorts descending. Raw filter / object sorts still accepted.
• Warnings, not rejections — an unknown top-level field is ignored, the call still runs, and the result's warnings names the field and the fields the operation accepts; a property name that differs only in case is corrected with a warning. No extra round-trip when the rest of the payload was right.
• 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.
• Short file refs + image reads — NOTION_FILE_URLS=ref swaps Notion's ~500-token signed file URLs for notion-file: refs; get_file_url mints a fresh URL and get_image returns the picture as MCP image content. See Files.
• 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_read, notion_write & notion_describe)

The server exposes exactly three MCP tools — your client loads three schemas regardless of which of the 47 operations gets called. notion_read runs the read operations and notion_write the write operations; each tool's operation field is an enum of exactly the operations enabled on this server, so the menu ships with the tool list, a client can validate a call before sending it, and a name sent to the wrong tool fails in one round-trip with a message naming the right one.

Per-tool permissions

MCP clients grant permissions by tool name, so the split lets you approve reads once and keep writes behind a prompt. In Claude Code (~/.claude/settings.json or the project's .claude/settings.json, with notion being whatever you named the server):

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

Cursor's MCP settings offer the same per-tool allowlist. notion_read is annotated readOnlyHint: true and notion_write destructiveHint: true, for clients that read annotations.

notion_read

{ operation, payload } for any read operation — search, page and block reads, database queries, users, comments, files.

{ "operation": "search_pages", "payload": { "query": "Q3 plan" } }

// a page as markdown, addressed by the link Notion copies
{
  "operation": "get_page_markdown",
  "payload": { "page_id": "https://www.notion.so/Q3-plan-1f3c1a2b3c4d5e6f7a8b9c0d1e2f3a4b" }
}

notion_write

{ operation, payload } for any write operation, where payload is a single object or { items: [...] } for batch mode.

// single call
{
  "operation": "set_page_title",
  "payload": { "page_id": "<page-id>", "title": "Q3 plan" }
}

Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL — paste what Share → Copy link gives you and the server extracts the id. A block link's #fragment is used for block_id fields and a database link's ?v= for view_id fields.

// batch
{
  "operation": "set_page_title",
  "payload": {
    "items": [
      { "page_id": "<p1>", "title": "First" },
      { "page_id": "<p2>", "title": "Second" }
    ],
    "atomic": false,
    "concurrency": 3,
    "idempotency_key": "rename-pass-2026-07-02"
  }
}

// markdown shortcut (create_page, append_blocks, update_block, update_page_markdown)
{
  "operation": "create_page",
  "payload": {
    "parent": { "type": "page_id", "page_id": "<parent>" },
    "title": "Notes",
    "markdown": "# Heading\n\n- [ ] todo\n- [x] done\n\n```ts\nconst x = 1;\n```"
  }
}

// a database row: plain property values, typed from the data source's schema
{
  "operation": "create_page",
  "payload": {
    "parent": { "type": "data_source_id", "data_source_id": "<data-source-id>" },
    "title": "Write the report",
    "properties": { "Status": "In Progress", "Priority": "High", "Due Date": "2026-10-01", "Tags": ["q3", "docs"] }
  }
}

// upload a file and place it on a page in one call
{
  "operation": "upload_file",
  "payload": {
    "source": { "type": "path", "path": "~/Desktop/chart.png" },
    "attach_to": { "block_id": "<page-or-block-id>", "caption": "Q3 revenue" }
  }
}

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

Returns the JSON Schema + working example for one operation, plus tool (which of the two runs it) — useful before complex calls (filter expressions, mixed block batches, database property definitions).

{ "operation": "query_database" }

Operations menu (47 ops, plus one alias)

Read operations (get_*, list_*, search_pages, query_database, query_view) go through notion_read; everything else through notion_write. The notion://operations resource lists the tool next to each operation.

The authoritative list (with batchability) is served as an MCP resource at notion://operations.

MCP resources

Clients that support resource attachment (@-mention) can pull Notion content into context without a tool call:

Dynamic resources route through the same auth, rate limiting, and access gating as tool calls.

❓ Troubleshooting the Notion MCP server

• 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.
• "No parent page configured" — pass parent in the call, or set NOTION_PAGE_ID.
• multi_source_database from query_database or create_page — the database has multiple data sources. Call list_data_sources, then pass data_source_id (or a data_source_id parent) instead of database_id.
• A successful result carries warnings — the call ran; each entry names a field that was ignored (misspelt or misplaced) or a property name that was corrected. Fix the payload next time, nothing to retry.
• 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 · Notion API reference · MCP spec

💬 FAQ: Notion MCP server

What is the Notion MCP server and how does it work?

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 three MCP tools the AI calls to read, write and inspect Notion operations. You authenticate once with a Notion token; everything else is natural language.

How do I connect Claude to Notion using MCP?

See the Quick start: get a PAT at app.notion.com/developers/tokens, then one claude mcp add command (Claude Code) or one JSON paste (Claude Desktop). Non-developers: the complete walkthrough assumes nothing.

What's the difference between this and Notion's official MCP?

Notion's hosted MCP (mcp.notion.com) is OAuth-only and built for interactive chat — it can't run headless (Notion says non-interactive authorization is in the works, but not yet). Their open-source server is, in Notion's words, "no longer actively maintained" and exposes one tool per endpoint. This server authenticates with a token (works in CI/automation), exposes 2 tools dispatching 47 operations, batches mutations with idempotency and retries, and slims responses to cut token cost. See Which Notion MCP should you use?.

Can I use it with Cursor, VS Code, ChatGPT, or Cline?

Cursor, VS Code (Copilot agent mode), Cline, Zed, Continue: yes — install badges and config blocks are in the 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 with a bearer token.

Is it safe to give an AI my Notion token?

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 if a laptop is lost. For agents that should never write, set NOTION_READ_ONLY=true.

Does it work with self-hosted or local-only LLMs?

Yes — anything that speaks MCP stdio (or Streamable HTTP) works. The server doesn't care what's on the other side of the protocol.

🔒 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. There is no telemetry, no analytics, and no server of ours in the path: nothing you read or write in Notion goes anywhere else. The token stays where your MCP client keeps it (its config file, or a keychain / secret store for clients that have one). With HTTPS_PROXY set, traffic goes through your proxy instead. get_image fetches only the signed URLs Notion returns for files it hosts, never a URL supplied by the model, and upload_file reads a local file only when asked to, inside NOTION_UPLOAD_ROOT when that is set. 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
echo "NOTION_TOKEN=ntn_xxx" > .env

npm run build       # tsc -> build/
npm test            # vitest suite
npm run inspector   # MCP inspector against the built binary

Local build instead of npx:

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_xxx \
  -- node "$(pwd)/build/index.js"

Everything the server logs goes to stderr, as before, and is also sent to the client as MCP notifications/message entries (logger notion-mcp-server), so it shows up in the client's own log view — VS Code's output channel, MCP Inspector, Claude Desktop's logs — where stderr is usually hidden. The server honours logging/setLevel; the default is info. At debug you also get one line per notion_read / notion_write call (operation, batch size, duration, ok or error — never the payload or page content).

End-to-end smoke test

npm test runs against a mocked Notion client. scripts/e2e.mjs drives the built server over stdio against a real workspace — every read operation, the resources and prompts, notion_describe for every operation, and (with --write) every write operation inside one throwaway page:

npm run build
printf 'NOTION_TOKEN=ntn_...\nNOTION_PAGE_ID=<page the token can write under>\n' > .env   # gitignored
npm run e2e                      # read-only pass
npm run e2e -- --write           # full pass; creates one page under NOTION_PAGE_ID and trashes it at the end
npm run e2e -- --write --keep    # keep the test page for inspection

It prints a PASS/FAIL table per check and lists any operation the run did not reach, and exits non-zero on a failure. It is not part of CI.

🤝 Contributing

PRs welcome. Fork → branch → commit → push → PR. Run npm test before submitting.

📄 License

MIT — see LICENSE.

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