SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsnotion-mcp-server

notion-mcp-server

Context-efficient Notion access: pages, databases, blocks, comments, files and templates through a minimal tool set, with token auth for headless use.

Open website

About this tool

Purpose

notion-mcp-server is an MCP server for Notion, used to connect MCP-capable AI agents (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed, etc.) to Notion, letting AI create pages, query databases, append blocks, apply templates, post comments, and upload files using natural language.

Main capabilities

  • Authenticates with a single token and can run headless, suitable for CI, cron jobs, background agents, and self-hosted deployments. The officially hosted Notion MCP only supports OAuth and requires manual click-through authorization; this server uses a token approach.
  • Saves context: the official open-source server loads 24 endpoint schemas on connection, about 17,163 tokens, and resends them with every request; this server loads only three tools, about 1,005 tokens, a 94% reduction (about 17x), and only fetches operation schemas when a task actually touches them.
  • Streamlined responses: reading the same page content, this server uses 82% fewer tokens than the official server (an 88-block page drops from 26,071 to 4,568); a 25-row database query uses 81% fewer; page objects use 68% fewer. The optional verbose: true returns the raw SDK shape.
  • Built-in batch modification with atomic rollback, idempotency keys, rate-limit retries, and self-healing validation errors.
  • Three tools carry 47 operations: notion_read performs reads, notion_write performs writes, and notion_describe returns the JSON Schema for an operation plus available examples.
  • Every id field (page_id, block_id, database_id, view_id, etc.) also accepts a Notion URL.

Usage

  1. Get a Notion token: open app.notion.com/developers/tokens → + New token → name it and select a workspace → Create token → copy the ntn_… value. A personal access token can see everything you can access, with no need to share page by page.
  2. Install and configure:
    • Use add-mcp to automatically discover and write MCP client configuration (supports Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed, etc.). -g installs at the user level, -a claude-code skips the selector, --all writes to all clients. Be sure to keep the --env flag, otherwise the token is not written and every call will fail authentication after the server starts.
    • Manual configuration writes an mcpServers block (such as Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline settings, Zed, Continue, etc.).
    • Claude Code uses the stdio 2025 protocol by default; you can set MCP_PROTOCOL_NEGOTIATION=auto in environment variables to probe MCP 2026-07-28.
    • Cursor and VS Code (Copilot agent mode) have corresponding installation entry points; VS Code stores the token as a secret input.
    • The repository provides gemini-extension.json, which can be installed as an extension (the token is stored in the system keychain, and the server is started with npx).
    • When Claude Desktop has no Node.js: download notion-mcp-server.mcpb from the latest release and double-click it (or drag it into Settings → Extensions), then paste the token as prompted.
    • Docker/Podman/OrbStack: stdio must add the -i flag; the image is OCI-compliant, and Podman, OrbStack, colima, Rancher Desktop, Finch, and nerdctl can use the same flags.
  3. Try it: in a new conversation, say "Use Notion to create a page called 'Hello from my agent' and add a checklist of three things to try today." The AI will call notion_write and reply with a live page link.

Suitable scenarios

  • Find rows in the task database whose Status is "Doing" and determine whether they are overdue (typed where filtering, flattening rows).
  • Batch rename 50 pages: one batch call, 10-way parallelism, idempotent retries.
  • Create a page from the "Weekly review" template and fill in a summary.
  • Rewrite a spec page: do a markdown round trip via get_page_markdown → edit → update_page_markdown.
  • Comment a summary on yesterday's meeting notes.
  • Upload diagrams to a design page (single-segment and multi-segment upload).
  • View a defect report screenshot and explain the issue (get_image hands the image itself to the model).

Limitations and Considerations

  • Permission scope: can read pages you can access, create and update pages and databases where you have edit permission, comment and upload files as yourself; cannot access pages you cannot see, bypass workspace permissions, act as another person, or change admin settings. The scope of a personal access token is your account.
  • Token validity: personal access tokens expire 1 year after creation (Notion documentation). Recommend setting a reminder for the 11th month.
  • Revocation: app.notion.com/developers/tokens → Revoke next to the token, effective immediately; workspace admins can revoke anyone's token from Settings & members → Connections → All personal access tokens.
  • Most object_not_found errors are wrong authentication choices (an internal integration token not connected to the page); you can switch to a personal access token.
  • The environment variables NOTION_ALLOWED_OPERATIONS (allow list) and NOTION_BLOCKED_OPERATIONS (block list) accept comma-separated preset groups or exact operation names; names are case-insensitive, unknown tokens are ignored with a warning, the block list takes precedence, and an allow list that resolves to zero operations disables everything (fail-closed).
  • NOTION_CONFIRM_DESTRUCTIVE=true keeps destructive operations and asks via MCP elicitation before execution; refusal or cancellation returns confirmation_declined; clients that do not support elicitation return confirmation_unavailable.
  • Control is per-operation, not per-parameter: update_page_markdown is a write operation that can replace page body content; blocking destructive operations will not disable it. To guarantee no modifications, use NOTION_ALLOWED_OPERATIONS=read or NOTION_READ_ONLY=true.
  • Uploads: upload_file accepts base64, a public url, or a local path; a path source can read any file readable by the server process, so NOTION_UPLOAD_ROOT should be set to restrict paths when the model composes them.
  • File URLs: Notion generates a new signed S3 URL for hosted files on every read (about 1,650 characters, about 500 tokens, valid for 1 hour); NOTION_FILE_URLS=ref can replace it with a short, stable reference in lean responses.
  • Remote/HTTP transport: default is stdio; set MCP_TRANSPORT=http to switch to a remote endpoint, serving MCP Streamable HTTP at /mcp. The process is single-tenant: every request acts as the NOTION_TOKEN identity from startup. Before binding to a non-loopback HOST, set MCP_AUTH_TOKEN and place an authenticating reverse proxy in front.
  • Upgrading from v1.x or v2.x: environment variables are unchanged, the tool surface changes to notion_read + notion_write, and notion_describe stays the same. See MIGRATION.md for details.
  • The repository does not provide other pricing, cost, or specific platform support information in this material, so none is provided for now.

Related tools

Browse category